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Introduction 


The Acorn C compiler for the ARM processor is a foil implementation of C 
8-9 defined by rbe October I9U6 Jrsft ANSI language Handsrd. This manual 
is a reference re*i designed w auainpany the Lfcitp Proposed American 
iVammuf 5-rondard for Information Systems ■ C Programming Language 
document (October 1986) and should therefore be read in conjunction with 
!i. The compiler also has a Portable C compatibility mode, 

ABOUT THIS USER GUIDE 

Wc assume that the reader of this User Guide has a working knowledge of 
L’. The Guide does not act as an introduction to C. Subsequent chapters and 
appendices contain information on: 

* Installation and use of rbe compiler, in Hon,' to ms till, d?iJ im me compter, 

* How Acorn C implements those aspects of the language winch ANSI leaves 
to rhe discretion «.'* the implementor, m Implementation details* 

* How Acorn C behaves in those areas covered by Appendix A.ft of the draft 

standard, in Standard definition 

* The additional libraries for ibe Arthur operating system and the Window 
Manager (Wimp), in Arthur opera [mg system library. 

* How to handle procedure entry and exit in assembly language, so you can 
write programs which interface elegantly with the code produced by the C 
compiler in Assembly language interface. 

* Messages pn.hjLsced by the compiler, g varying degrees of seriousness, in 
Errors and wonting;. 

* Using rhe compiler m Ets Portable C Compiler compatibility mode, in 
Usmg die PCC mode. 


Calling other applications from C in a manner which allows control to 
return to the C program, in Coifing Applications from C, 


[f you m'fvl mlcirmiition of 11 more introductory nature, you could retcr to the 
follow mg hooksr 

* The C programming by B\V Kemiglum ..tn I DM Ritchie, 

published by Prentice-Hull, Englewood Cliih, NJ, USA This i*. the anginal 
C L bibl«', still useful tor a description of PCOsryle C, hut superseded in 
other respects b\ Harfeison and Steele. 

* A C Rje/ertmet MaimaJ, 2nd edition by >.unucl l 1 HarbfiMn and Guy L 
Steele Jr, published by Premkc*H«U, Englewixxl Cliffs, Nj, USA, This is a 
very [borough re/erenee guide I ■ > C, including .1 useful amount ol information 
on rbe proposed ANSI draft C, 

* C Language by Friedman Vi igner-LV.hler, | h-hi-J by Pitman, 128 Long 
Acre, London UK. 

* t. Pii^jlr Boot K\ W n R Fewer, published by Prentice-Hall. Englewood 
Cliffy NJ, USA. 

* The XfOPEN Fcmabiliry Gtiide published hy Ebevict Science Publisher 
BV. |iX*0 BZ, Amsterdam, Netherlands 

conventions used 

Throughout 1 ho User Uuide. r br,' i 1 1 lowing convention ls used i.ir text that 
appears on the screen, tut C keywords. miu.no, library routines etc. A 
typewriter style font is used for reset ro he types! m ts, and italic arc used 
to denote classes of iTcra which would be replaced m the command or 
message by actual objects of the appropriate type. bi>r example: 

cc options jfde names 

means that you 1 * shmvn, and replace option* and filenames by 

specific example*. 
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This section describes, first, how to install the C compiler, second-, rhe 
mimmu ednventurns used bv Atom C. and finally, how to run the compiler 
and control various aspects nl its operation 


INSTALLATION 


The diagram below shows the directory structure of the C distribution disc 
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L pon receiving your disc* you ikuuid make i working copy and keep the 
original in ■= place- To mob: the copy, enter the following command: 

^backup 00a 

The program will prompt you to insert a destination disc tie a blank 
formatted BGOk disc) in place oi the original disc rhat you wish ro copy. The 
Arc/itmedes L-ier Guide tells you how to format u. floppy disc. 

The programs mstallHD and LnstallNET art” provided on the floppy disc to 
enable you to install C on a hard disc and Econct network respectively. 
These can he run by clicking the appropriate icon from the desktop, or from 
the Arthur * prompt hy typing 

w installHD 


or 


- installNET 

as appropriate. Ef you have an Econer file server, you will need to log on 
with system privileges in order to copy files mro the library. Jr is 
recommended thar you copy the structure provided on rhe disc supplied, 
except that dire crones h, and . will be created at user level Remember 
ro set file attributes for global use. 

Before running the compiler, you should, ensure that The.- floating pom? 
emulator is installed, To do this on Arthur L2. you must load the emulator 
from thi- C Jem- If you arc not sure what version of Arthur you are using, 
perform the '■ V. 'Wing -teps to find out; 

* quit the desk trip 
■ from the * prompt, type 

* f x 0 

A message of rhe form 


H 


OW TO INSTALL AND 
RUN THE COMPILER 


Arthur 1 * 2 j <01 Septeu.ber 198 ’) (Error number iF 

will be displayed. If the version numtx-r ls 1-2.0, insert the C disc and type 

$.lib*.fpe 

This installs the floating paint emu] a rot. 

GETTING STARTED 


Having backed up the C distribution disc, insert v-.w working disc an the 
Jjlvu and select the directory $ .ARM. BENCH by entering the following at 
the * prompt: 


* DIR $.ARM.BENCH 


There arc four {-sample programs provided on the disc (see the directory 
structure Jiagn-im aboveh 


■ Ball s64 

* He1loW 

* KowToCall 

* Sieve 


colourful ^Faphics demon strati m 
simple test program 

see the section entitled Calling Applications from C 
standard test program 


To compile and link the program HelloW, type 


■ec c.heilow 


(note that upper and lower case letters are interchangeable in the 
filename). 

When this process n completed. the * prompt will return under a Brushing 
message displayed on the screen. To run the program, now type 


*he11 gw 


and the program will print the message Hello World on the screen. 

Balta64 makes use ot of the graphics facilities of your Archimedes 
personal workstation, and needs linking with the .'Arthur library after 
compilation- The compiler will do this tor you it you type 

*cc -Arthur balls£4 

and then run the program hy typing 

*balisH 

Tress the esc | key to leave this proem m 

The cc command and Us assotn ned c omen no cl*, such as where the C 
compiler expects to Sind - i TCe, lihf.m\ object and image files, is covered 
in detail in the sections which follow. 


NAMING CONVENTIONS 

The Atom C system r in common with many other t; systems, uses naming 
con cent ions to identify the rout classes ot tile involved in the compilation 
and linking process Many Systems use conventional suffixes lor tbi«- For 
example, the suffix . c denotes C ? nirce files i *n L'N'IX " and MS-DOS 1 * 1, 
systems- This convent urn ctashe.% wiih Act.mV use ■! rhe period character 1- 1 
in purlin am as tr is more natural undtt Acorn filing systems ro use a prefix 
mechanism, eg .7 . f : o, where c is the directory containing t source files, and 
fqc is the filename. 

However. por nihility is m increasingly important issue in the C world. To 
this end, the At in C system recognises the 'standard' hie naming 
contentions and performs the appropriate tranoformatnms ro construer valid 
Arthur pathnames. The lolkiwmu actions imnttiari.se rhe com 1 ersT urns for 
referring to source include, object and program files. 


fi 
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Source tiles 

Semite tilts will be bolted fur m subdirectory c- To aid portability, a file 
too. I- will he looked for in g,q f f ■ -I, where (f means the current 
dkecfory. 

Include tiles 

The way in which the compiler Jeab with included fitefl depends on 
whether the name of the filename in [lie * : • • 1 n:ie directive between 
angled brackets < > or double tfli.mmoti murko H “V. The former case 
implies that the File is a System' one, the larrei that Li is t 'user 1 tile 
Simply put, system include files Lire searched h r within the compiler 
built-in Filing system, and then m the 'system include path' This i> read 
from the environment variable C $ L i b ront if possible, iuhcrwi.se n defaults 
to fi. a rr, die, User include lilts - that is, those enclosed in double 
quotation mark:-. - are -reichi in the Currenr directory, rhen the system Lndud.e 
parh, 

In hi nil cases, ,m inter mediate Set of directories to icarth JT14V be specified 
using the -1 command-line flag. Much more inform.itum about include file 
processing may be found in the section on the - I and - (lay." 1 el- w 

Ohject files 

The object file* created by the compiler arc stored in die directors- within 
the currently selected directory 1 hu§ the result ■ .1 compiling **pr will 

be found in a , expi. 

Compilation N*t files 

if the - list keyword is specified, then a file containing a compiLi inn 
listing toi each compiled source file is treated in the directory 1 Thus 
compiling the hie : -expr with rhe keyword -list will result in the list 
file (? „ 1 . expr being Created 


Library files 


The default link step activated by the compiler searches for libraries, m the 
'system library path' As With the system include path* fhe compiler tries to 
read the system library path from the environment variable CSLibroot. If 
this isn't defined, die path 5 * a cm. ciib is used instead. In either case, . o , 
is Appended rn the directory name, 

Standard library riles ate called ansilib, ArthurLib and Super Lid, 
These contain the code for the AN'S! library* the Arthur-specific library and 
the Spring Boa rd/Brasil library respect ively The command line flag -i may 
be used to override this search path with one or more user-spec]hej ones* 

Program files 

The res: It : linking the c 'irp ltd versiont of the source files given in the 
command hne with the libraries is an executable program file. This is 
named 

• file/, where filtl is the nnmr of rhe fimt source file given on the command 
line This convention may he overridden by use of the -o flag. 

As an example of these naming convent ions m use, consider the directory 
C-ench cm the distribution disc; 

The directory bench . c contain?' C program source- 

Bench . c .Sieve i- the -OatCr of a sample program wh^h computes prime 
numbers by the sieve of Eratosthenes. It would be referred to in a command 

line as sieve. c or c*sieve. 

Tho compiles to produce the oh jeer file bench .o.sisve 
This obie^t rde is linked with the standard library to produce the 
executable program t ench . sieve. 

The compiler does nor check whether the filenames you give are acceptable, 
te contain only valid character!? and are of acceptable length - rhis is done 
by the filing system. 
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COMPILING A SIMPLE PROGRAM 

The compiler can only he used from the T prompt- It you an* using the 
desktop, tecum to the * prompt by clicking the select button on the Exit ken. 
Nest, load the He siting point emulator by Typing. 

rmload library*fpe 

You are now ready to run che C compiler. 

The compiler is called cc, To run it, type: 

” cc opriems /iknamci 

The- rjpif.uu ire Jbribed in derail below. They allow you to control the 
COrEifiLaunn K t •! example, overriding default names, Often, jn-t rise Iisr 
of one or more filenames is all that is required following The CC command. 
For example, suppose you have created the following program; 

finelyda <atdio<h> 
int main () 

I 

print f ( "Hello world t \fi n ) ; 
return 0; 

I 

,ind stored ii a?, e .hello. To compile it, you enter the command 
kc hello 

Assuming that everything j* correct, the compiler will give you a message 
similar to the following; 

Norcrc-ft AFW C (with debugger support) l.fiSA Hay 20 
1908 


Tin* compilation producer the object file o« he.l - o. The compiler 
automatically issues the Link command necessary ro combine the object file 
with the standard librario in order to projiu-c rhe executable hie c.illud 
n.aiio. This cun br executed using the command k hello. 

You can suppres* the I ink mg stage by specifying a command line option 
This. Hrid other opium*, dte described in the section below 


COMPILER OPTIONS 

Y.m c.ni Control many aspects of the compile r> operation by appending 
options m the command cc All options are prefixed by rhe minus sign - 

Options come in two forms. Thu- first .ire Lev wot is Theie ,ire multiple- 
character options and control Acorn ot Arihuf^apecific aspects of the 
compiler Keywords .ire recogns-HTti in upper or lower case. The second form 
of option is the fi *g. \ rhig o a single letter. The case of the letter is 
usually unimpon jut m the C compiler under discussion However, UNIX 
compilers only recognise one rurm {either the upper or lower case one, 
depending nn the flag} ,md this one should be in preference 

The quartern of rhe t4*c of rings ta nwsi important when you arc considering 
porting ‘make 1 fife* to other systems. By using ihc ‘universal 4 sent,is of the 
cc command, you can move your system rn different environments with the 
minimum amount oi work. 

The keyword options are: 

-heir.- Give a description of rhe compiler's coni in and syntax- 
-arr'n_: Add the Arthur Interface library to the list csf Standard' 

libraries passed i< the linker. This is only valid under the Arthur 
ope rating stem 

-super Add the Brazil Mipenisor interfilee library to ihe list of 

‘standard' libraries passed t«i- the linker. Thih is only valid under 
Brasil, SpringBodtd tnd Arthur. II the -z ti.hu i keyword is a bo 
given under Arthur, then rh.u rakes priority. 


10 
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-pcc Compile oULsryle parable C compile C. This- is often 

referred ro as liemighnn and Ritchie (Ci-r just K £i R1 C.T. This 
changes rhe syntax that is acceptable to the compiler, but the 
default header and library files are still used. See the section on 
this option for more details 

-list Create a listing file Tho consist? of lines of Source interleaved 
with error and warning message? Finer control over the contents 
of thus file may be obtained using the -f flag (see below). 

The flag options sire listed below. Some of the-e are followed by an 
argument Whenever this i? rhe case, rhe compiler allows whitespace to lie 
iniierted between ihe (lag letter and the argument However, thin is not 
til way? true of other C compilers, so the syntax given lists- only the (orm that 
would he acceptable to a LI NIX C compiler. Si mil ark. only tine case ot the 
letter that would ht accepted by a UNIX C compiler is shown, 

The description- ire divided mi" several sections, iso ihai (lags controlling 
related aspects, of the c. mpder'? operation ate grouped together. 

Ctmiroiling the Linker 

-c Do not perform the Link step. This merely compiles the source 

program (t), leaving rhe object fite(.s) in the o directory 

NE This h different (rom rhe -C opELon. describeJ below. 

- I hfri This specifies a list of libraries which will he used in ihe Link 

command issued by the compiler. The list of libraries to he used 
follows the flap lwith optional white-Apace between the flag and 
rhe listh and use-- commas ro *ep.irate items in rhe list. 
Alternatively, multiple -1 flags may be used to specify more 
tb-in :rK.- hhfarv- Note that ihe libraries given by tho option .ire 
used iftsii'dji :.)/ the standard ones, not in addition to them. 

This flaa is not compatible with corresponding l. N[X C 
compiler opt ion, which has no direct equivalent under Arthur. 


Controlling the pre-processor 

The - I and - | flag* control the search paths Used when the compiler is 
looking for included hie*. Before describing thew rtagh, we explain ch.tr 
way in which the search paths .ire used. 

The list of paths comprises three separate elements. In order, these are the 
directory containing the current source file, any directories given bv -l flag* 
{in the order they appear on the command line', and finally the system 
include path' In the absence of any - j lla« on the command hoe, the system 
include path is read from the string variable :$ . is: : ot- In rhe absence of 
that variable, S . arm, clib is used. 

When a directive of the form 

* incl ude cfil^najne* 

or 

#include ri filename” 

is encountered* the compiler behaves as follow*, 
if fid©name is a 'rooted filename, that is 

* an Arthur filename beginning wirh a S ir :m £ 

■ a UNIX filename beginning with a / 

■ „«-! MS-DOS ulename beginning with .1 \ 

then it js used as written iexcept thai UNlX-stcle and MS-DQS-styEe 
filenames are fust translated to equivalent Arthur filenames as described 
below). 

If filename i* not 'mored' tn ihe sense described shove, then the compiler 
looks for it in a sequence or places y directories) called the search path The 
search fwrh ss in three parts, tn order:: 


i; 
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the compiler's own in'memory tiling system: 

the directory containing the source file (C source or if .1 nc I uded header) 
currently being processed by the compiler (rhe ‘current place"); 
the remainder of the path, termed b\ concatenating the lists of directories 
given as command line arguments to - I flags with the system search path 
(see belowi The system search path i? searched last. 

It' rhe * included [tlename is given in mgle brackets <: and >, then the 
directory containing the current source file is nor searched, 

If the it included filename is given in double quotation mark* then the 
compiler's in memnn tiling system is not searched 

In Kirh cam.-?, to facilitate the porting of code from LMX and MS-DOS ro 
Arthur, UNlX^stiJe and MS-DOS-SIyle tilcrmtftfcs are translated to 
equivalent Archur-siyle itlenam.es. For example; 


. 'include defs.h 
..\clx*hash.n 
includes* h 

but 

system.defs 


is translated to 
is translated to 
is translated to 


Is translated to 


■„include*h,defs 

'.clx.h.hash 
r.. includes 


system, d-?f s 


{Similarly, the lists of directory names given ,v- hrgumtnt- to rhe compiler ? 
-I find - j command-line flags [see below] arc translated to Arthur format 
before being used). 


fthen a file > round relative to .tn clement of the -eareh path, rhe name of 
the directory containing that file becomes the new 'current place" When the 
compiler has finished processing that hie it restores the old current place. 
So, at any given instant, there is a ?nick of current places corresponding to 
rhe sock ot nested * me ludes 


Fur example* suppose the current place is l . include and that the 
compiler is seeking the l included hie "sys , ief . h n {or 


11 sya . h. de f s ", "sy s / de £ s . h". ere), How suppose rht* is. found in 
$. Includesys * h . def s. Then the new current p-lsue becomes 
S . include . sy s and fi&s *; iicluded by h .. dets, whose names are noi 
rooted, will he sought relative to ; . include .ays. 

In all this, the penultimate , c and . h components of the path are umiiied. 
These are Logically p*n"t of rhe filename - a filename ejnensiuti - not 
logically part of' the directory structure. However, directory names Other 
than c, h, O And 5 are not so recogruwfd las filename extensions) and are 
used 'a> is'. For example, the name sys .new. lets is exacth that: it Is nut 
translated to sys.defs.new and, if it is found, the new parr nt the name 
doe l Ft'come parr of the new current p :i rh 

Initially the system path i- 

the path given as an argument :o the -j command-line flag (nee below); nr 
i he value ot the system variable :3I ibract, if this is m and (here is no - j 
flag-, otherwise, 

? . artruci i.£> 

In the first case, rhe in-memory filing system is on^ried from the front >.i the 
path searched for # i ncl -do <filename - It can he reinitiated h using ihe 
pseudo filename : mem as an argument to a (lag or the - ; flag. IS : mow 
u included in the search pith in thb way, it position in the path h a< 
specified, nor necessarily first. *o you ^an mite complete a iwtd over where 
the compiler seeks ^included files. 

-: parfi This adds the specified directory to rhe list of places which are 
searched lor include files (after the in-memory nr source file 
director,, .according to the type of include file). The directories 
□are searched in rhe order in which they are given m -I options. 
The parti should end with the name of a directory, with no , h *, 
which is added automatic ally, 

- _i dir.t This overrides the system include pith with the list ot directories 
which follows rhe flag. The directories are separated bv commas. 
You can specify the memory file system in the list by using rhe 
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name :iem (in any ca&e) An example is 
ir.yh.drs f :mem f $ .pro j .public,hdlrs. 

-j is an Arthur-specific flag, and therefore non-portable. 

If chis flag is specified, only the pro-processor phase of the 
compiler is executed, The output from the pre-processor as sent to 
the standard output stream It can be redirected to .1 file using 
the usual methods, Bv default, comments arc stripped from the 
output, but sec the nest flag. 

This is used rn conjunction with -t above. It reinstates comments, 
so they appear m the output produced bv the pre-processor, Note 
that n is different from the -c flag, which 13 used to suppress the 
link operation. 

- rn--id This flag can be used To emulate ipraqua directives. The mod 
which follows if is the same sequence of characters that would 
follow the directive See the section tpragma Drnrctiv Bj for 
detinU. 

Controlling code generation 

The options described in this section control tn some way the production of 

code by the com pilef- 

-gmods Tins flag is used to -.pecify that debugging tables lor use by the 
Arthur Symbolic Debusa'cr should be generated. Er is followed 
by an optional set of letters which specify the level of 
information required. No modifiers means ‘generate all the 
information possible" However, the tables Can occupy large 
amount- <l memory - ■ it ss soreirthtirs useful to him it what is 
included as folio wit 

-gt Generate information on functions and top-level variables 

(outside functions) only, 

-gl Generate information describing each line in the rile. 

_ ____ 15 




gv Generate information Jescribing all vattables. 

The modifiers may be specified in any combination, -giv. 

c file This flaa specifies the mime of a file in which the output of the 
linker should be stored [r overrides rhe default, which is to n!se 
the same name ,i.s the root name ■ if the Iirst source hie mentioned 
on the command tine. 

l Tin, Hag causes The compiler res generate code which allows 

‘profiling’ ot ihe program to cake place The profiling 
information may he printed out bv call mg the function 
_jnapst Ore () just before the program terminates. 

When this option is given, the compiler embeds calk to a 'count' 
routine at the scan r each time non body. Whenever ir is called, 
l he mu one i licit men c s a JZ-bii counrer associated with the caller. 
The _■ ac SI -re I,) function prints the values of these counters, 
along with their associated addresses. It also prints the addresses 
of all of the program's function entry points, So that you can 
deduce how often each function {or purl thereof) was called. 

Note though that this doesn't tell you how' long the program spenr 
in a routine, only how often it was there {but, usually, rhese are 
related values). 

5 It this flag, is specified, no object code is generated and. 

natuiully, no attempt is make to link it. Instead, an assembly 
listing ot the code produced is written m a file called s , : } e, 

where is the name ol the source file i si ripped of any 

directories or suffixes). 

Dsym Define s\m m j pre>processor macro, as if by a tine 

Sdefinesvm 1 


at ihe head of th'- s urCe file 
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-Ojym UndctLne ivm, as if by a line 
ft undef svm 

at the head of die source file- This may be used to cancel the 
effect ul otherwise predefined symbo-h, eg A PM (A macro ARM 
i.s predefined„ and ha- the value 3), 

Controlling warning messages 

The -w option controls the suppression of warning messages. Usually the 
compiler is very free with it-- warnings, in this tench h* indicate potential 
portaHlsty or i>thrr problems, HtfWcVcr. toi■ man 1 , ni.ioh messages' can he a 
nuance in the early stages of developing a program, they may be 
disabled- 

-Wmpd If no moJatter letters mod are given, then all warnings arc 

suppressed It one or more lerrers follow the flag, rhen only the 
■class of warning*- controlled by those letter* .ire suppressed- The 
letters are: 

a Give no Use of = in a condition ccntsxt warn mg. This 

given when the compiler encounters statements such as 

If (a^bj 1... 

where it is quite possible that == was intended. 

c Giveno<op> implicit cast of pointer to non- 

pqud I o: nter warning. Pointer casts should always be made 
explicit using i type * i .iperaEcm, except in the case of NULL, 
which is a universal pointer, 

d Give no Unused static definition warning- If an object 

was defined to be static and was not referenced in the same file t 
if: can perform no useful function ami it therefore redundant. 


n Give no Implicit narrowing east warning. This warning is 

issued when the compiler detect a an assignment of an expression 
ro an object of narrower width (eg . n> to short 1 This can 
cause problems with loss oi precision for certain values. 

p Allow characters .after ieise and iendif directives. Normally 

such characters are not allowed and their presentr could signify 
trouble. 

5 Give no Short is slower than int on this machine 

warning. The statement is true, but there's a limit to the number 
of times you have to be told... 

v Give nts Imp 1 icit return in non-void context 

warning. This is must often caused by a return from a function 
which was assumed to return i r-t (because no other type was 
specified) but ss in fact bang used as a void function, 

z Give no Array [0] found error. 


Com ml ling additional com pile? feature* 

The -t flag described in this section controls a variety of compiler features, 
Lncludins certain checks more rigorous than usual. Like the previous [lag it is 
followed by modifier letters, At least one letter o required. 

a Check for certain, types of data flow anomalies. The compiler 

performs Jut a flow analysis as part of code generation. The 
check* enabled bv (his option can sometimes indicate when an 
automatic variable has- been used before it has been been 
assigned a value, 

e Check that external names used within the tile are still unique 

when reduced to hlx case-insensitive characters. Some linkers only 
provide six significant characters m ihdr symbol tables. This can 
cause problem? with clashes it ,i system uses rwo names such as 


H 
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getExprl and get Expr 2, which art only unique in the eighth 
diaracTrit- Noie chat the check can only he made within one 
compilftiion unit (source hie) so cannot catch all such problems. 
(Note also that the system under discussion allows external 
names of up to 256 characters, so this U rerally a portability aid-) 

f Do nor embed function names in the code area The compiler 

Joes this to make the output produced by the stack backtrace 
function (which is the default stun id handler) and _map.yit.cf a i i 
more readable. Removing the names horn the compiler makes 
the code slightly smaller (cyptcallv 5 %) .if the expense of less 
meaningful backtraces and _mapstoca i outputs. 

h Check that alt external objects aie declared in -some included 

Header File, and that ail static objects are used wtthm the 
comp liaison unit in which they are defined These checks support 
good modular programming praetkes. 

± In the listing tile (see -] i. at) include the lines from am files 

included with directives or the form. 

#include "file 11 

As above, but for files included by lines of rhe Form; 

¥include <fj le> 

rr. Give u warning tor pre-processor symbols thru ate defined hut 

not used during the compilation. 

z. Report on e splint casts of integers into pointers, eg 

char *cp " (char *] anInteger; 

Implicit cast'- at* reported anyway t unless suppressed by the ~ 
wc option- 


u 


By default, the source rest as 'seen' by the compiler after 
preprocessing (expansion) is listed, If -tu is specified then the 
wnercfiiinded source text, as written by the user, is listed. 

Consider the I me 

p - NULL; 

By default. this wilt he listed as p= < 0 3 with -fu specified, as 
p=*IULL;. 

When writing high-quality production software, vou are encouraged to use at 
Seii 1 ;.! the -f 5 h options in the later stages ot program dnropment ' the extra 
diagnostics produced can be annoying in the earlier stages,). 

COMPILING AND LINKING 

Ass i-ilrciidv shown, to compile and link rise simple program shown above yon 
would type: 

cc hello 

This produces the executable program hell.. T>‘ produce -i program with j 
different name* you would use the -c option, eg: 

cc “O greeting hello.c 

This time the linker would produce a program that you could run using the 

command *q resting- 

When writing programs that u*r several source files, you may want to 
compile them selectively and perform the link as a separate .step- For 
example, if a program consists of the files el . o t et? * c and e3 * c* and you 
have just edited el . you may want rq compile this* then link the object 
file with the two other files: 

cc -c e2*c 

link -o expr o.el o.e2 o .e3 -lib 5 *artn,qlib*o + amgilib 
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Alternatively, 

ce -o expr el.o e2,c e3.o 
does the trick 2 

Sec the linker documentation for more details on linking- To maintain 
complex, multi file programs, consider using a ‘make’ utility such as AMU, 
which forms part of the Software Developer's Toolbox 

To compile several Jitferem '"Uri-e progi mo and link them all together 
into one executable file, list all the filenames separ:iced bv spaces The 
name of the executable program is taken from the first filename given 
unless -o pragna/ne is used- 

For example, The command: 

CC mainprog util extra 

compiles the .sources c, ma I npr : o. c . ut j md , e *t - s into rhe object 

files □ . mainp rog, o, uti 1 and ofa, and then links ail three object 
files together with the standard library to produce the executable program 
jna inprog, 

#pragma DIRECTIVES 

The ANSI standard specifies a pre-processor directive rp tagma, which 
provides an implementation--.pee if it TWnn> ol controlling the behaviour erf 
the compiler, 

The following iprriqra directives are recognised by the compiler m lower 
or upper case In each case n must be either I (to enable the feature) or d 
(to dibble it). 


#pragm,a 

Tin? directive is u<Led io enable and disable the generation o( ccnJe which 
cheeb f'Jf *iaek overflow. If n is I, *wck checking C(\k will he generated; 
this is the default action It it is ■, no stack-checking code will he generated 
[t r is not presenr. the SE»ek checkinn stare 15 restored no its default, le is 
enabled, 

You should rarely need to use this Option The 1, Union of sr;^ k-cheek mg 
code ro a function only adds (generally) Two instruction* nd Two cycles 
flew than O-Sjis} to (he exet urnm time of a iuncisno m i|ie case of n. > 
overflow. 

One occasion when it would he used i- in u riting a signal handler for the 
SIGSTAK event. When this ixciiio. ’tack overflow has already been 
detected, so checking tor it ipm m the handler Would result in a fatal 
circular recursion 
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This th.ipter give* dermis a f tKonc ■? ■! rhc compiler which The dwfi 
ANSI standard identifies as imfikmemaEion^lefmed,, find sume other points 

nf mrfri>r ID programmer'' They Ate gmupej here by subject; -LLlum Hi liHS 
rhe pinriT.i requited m he documented h> nur in appendix A ,6 'I the Juti 
siimdarJ, 


IDENTIFIERS 


Identifiers can be of any length They art* truncated hy rhe compiler ro 
characters, all of which are significant *tnc standard requires- a minimum nt 

31 ). 

The source character set ts determined hy the hoM ipch-mitK nwem Upper 
and lower case chm»ctcr> are distinct m .ill denimem, hoth [mental and 
external 

DATA ELEMENTS 


The siu- 1 ' oi Jam elements ate .is to i •■- 
Type Sue > n hits 


char 

6 

short 

16 

lilt 


long 

M 

float 

32 

double 

64 

long double 

M 

all pointers 

32 


L subject fo future change) 


Integers are represented in nvo* complement form. 

Data item* • -I type zhai are .nsignea hy default, though (hes may he 
explicitly declared us si jned chsr oruns ; jf-J char. Single-character 
yon*!arxis are rlur- always positive. 


floating psunr quaniitief arc stored in the tIZEE forma: in double and long 
double quantities rhe word tiinMEfiiog fhe vign, the exponent .md rhe most 
significant part of the mantissa i- stored at the lower machine address 

Limit*; h . float and h . limit a 

The standard defines two headers* b„ limits and h. r Ic at. which contain 
com tarn dedaratb'^s describing the ranges of values which can he 
represented by die arithmetic types. The standard also defines mmnmnn 
values foT many i.»t these constants 

The following table sets out the values in these two headers on the ARM, 
and a brief description of their significance, the draft standard for a 
full definition of ihtlf meanings* 

Number of hat- in smaller . tyect that is not a bit field (ie a byte): 

CKAR_BIT 8 

Numeric ranges ,<\ iutegtr typtM The column on the left give- the numerical 
values 1 he column on the right gives the bit patterns (in hexadecimal 1 ' tli.it 
would hi interpreted as these values in C- Note though that when entering 
i i.irtfcanls you must be ureful about the site and signcd-nc“ of the quantity 
Furthermore* constants are interpreted differentLv m decimal and 
hexa decim«il/tcia|. Sec the ANSI! standard or Harbisun -ud Stecic for 
moie details. 


CHAH_MAX 

5-55 

Gxff 

CHARjall* 

0 

0x00 

SCHAfi_MA>: 

127 

Ox It 

SCHAR^MIS 

-128 

0x80 

UCHAR MAX 

255 

Oxf f 

SHRTMAX 

327*7 

Gx7f ff 

SHRf MTN 

-32788 

0x8GQC 
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USHRT_MAX 

65535 

Oxffff 

lK r X_MAX 

2147463647 

0x7fffffff 

INT_MIN 

-2147463646 

OxeODOOQOQ 

U1NT_MAX 

42*4967295 

Dxffffffff 

LQNG_MAX 

2147483647 

0x7fffffff 

LQNG^MTN 

-2147483648 

0x80000000 

ULO¥fG_MAX 

4294967295 

Oxffffff f f 

Characteristics 

of Soaring point: 


F1T_RADIX 

2 


FlT_ftOUSDS 

1 


Range; ol floating tvpes: 


FLT_MAX 

3.4Q2B2347e*3aF 

DEL MAX 

1.797693134S623l57je+30fl 

LDBLJHAK 

I,797693I348623I571*^300 

FU'JilN 

1.17549435e 

t-39F 

PBL_MIN 

2.225073S5850720138^-30B 

LDBL MIN 

2.22507385B50720136*-3Q J ' 


Ranges of bait rwo exponents: 


FL7_KAX_EXI 3 

I2S 

DBL_MAX_EXF 

1024 

LDSL_MAX_EXP 

1024 

F1T_M1N_EXP 

(-125J 

DBL_M1N_EXF 

1 -10211 

LBBL_MIN_EXP 

1-1021) 


Ranges of bitsc fen exponent a: 


FLT MAX _10_EXP 39 

D G L_MAX_10_ EX P 3G8 

LDBL_MAX_LO_£XP 308 

FI.T__MlM_iO_EXP {-371 
D&L_MIN_ i0_EXP [ -3C71 
LPSL MIN 10 EXP [-307J 


Decimal digits os prauitsi: 


FLT_ DIG 6 

D9L DIG 15 

LD3L_DIG IS 

Digits {base two) in mantissa: 

FLT j WANT_DIG 24 

DBL_MANI_DIG 53 

LD3L MADT DIG 53 


Smallest positive values such that (1-0 + it ! = 1.0): 


ETLT_ epsi lon 

DBL_EPSILON 
LDAL_EFST L ON 

STRUCTURED DATA TYPES 


1>192Q923Qe-7F 
2,2204460-5925031316-161 


Tilt drift irand-J-rd leaves details of the layout ot tlu- components nt 
structured data types up to each implementation The following points 
apply to the Acorn C compiler! 

■ Structures arc aligned on word boundaries- 

* Structure* arc .ifTanged with the ht-t n.tmed eom|H>nenr at rhe lowest 
address. 
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* char compsmeins are pLkfJ in adjacent bytes, 

* short components arc aligned .it cvcn-uddtcsrtcd byre 11 ;, 

* Alt other arithmetic type components arc word-aligned* as are pointers and 
ints containing bitfields 

* The only valid type for bitfields is ini, either signed or unsigned. 

* A hiEiLeld of type int is treated as unsigned by dcfhuh- 

* Bitfields must be contained within the bit* oi'an i n r ... 

■ Bitfields are allocated withm ints so that the first field specified occupies 
the least significant bits of the word. 

The to Hi ruing points apply ro pointer types: 

* Adjacent bytes have addrosc- whith differ hy ''he 

* The macro MULL expands to the value A with a pi -inter tvpe- 

* Casting between integers and pointers result* m no change or representation. 

* The compiler faults casts between pointers ro functions and pointers lu data- 
Pointer subtraction 

When two pointers are subtracted, the difference is obtained as if by the 
expression: 

( finn} a - [ int) b] { int ]■ sizeor (type pointed to) 

ll the pointers poult to objects whose we is no greater than four bytes* word 
alignment of diiia ensures that the division will be exact in nil ca-ie*. For 
longer types, such -■»>. doubles and structures, the division nm nor be exact 


unless both pointers arc to elements of the same Array. Moreover the 
quotient may be rounded tip or down hi different rimes, leading- to potential 
inconsistencies-, 


ARITHMETIC OPERATIONS 

The compiler performs dll cA the ‘usual arithmetic conversions’ set out in. the 
draft MiHidsrd. 

The following points apply to operations on the integral types: 

* All signed integer arithmetic uses a twob complement rtptesernation. 

* Bitwise operations on signed integral types follow the rules which arise 
naturally from two’s complement representation, 

* Right shifts on signed quantities are arithmetic, 

* Any quannrv which specifies the amount of a shift is treated as an unsigned 
S'bit value, 

* Any value to be shifted is treated as a iZ^bic value, 

* Left shifts of more than M give a result of zero, 

* Right shifts of more than 31 give a result of ret,■ fipm an unsigned. or 
positive signed value, -1 from a negative signed value. 

■ The remainder on integer division has rhe same sign as the divisor, 

* ll a value rt integral type is truncated to a shorter signed integral type, the 
result es obtained bv masking rhe original value to the length of the 
destination and then sign extending. 


28 


Conversions between integral types never cause exceptions to be raised. 
Integer overflow does not cause an exception to be raised, 
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* [nre-ger division hy zen■- causes an exception to be raised. 

The following paints apply to operations on floating types: 

* The ARM's floating point registers arc wider than stored floating point 
numbers, so that some values may be computed m a slightly higher precision 
than the stated hums imply. 

* When a d ub-fi nr long Iciuhia o converted to a float, rounding is to 
the nearest representable value. 

* t iaversions from floating to integral types cause rxc c-pnom to he raised 
onh it rhe value cannot he represented in a . un q ; r.t for :- : gns i 
ion q int in the case of c«inversion to an unsigned irr. rype i 

* Floating pomr underflow i> nor detected: any Operation which underflow-, 
returns 2cro. 

* Floating point overflow causes an essceptum i he raised 

* Floating point divide by wro causes an exception to he raised 

EXPRESSION EVALUATION 

The compiler performs the 'u?ual arithmetic conversion*' (promotions} *ei 
s. Hit in tKl- draft standard before evaluating .<m expression. 

* The compiler may recorder cxprt-'icmj involving only associative and 
commutative operators, i'v^ In ihe presence or parentheses. 

* Between sequence point>, the .ompiler may evaluate expression* in am 
order, regard Lew- !>r parentheses Thus the side effects of expressions 
he tween sequence points may occur in any order- 


Similarly, the compiler may evaluate function arguments in any order; 
moreover, this order rosy change from release to release 


■ The un.irv - operator, as defined in the draft standard, given a me am of 
specifying s sequence point other than the defined sequence points 

IMPLEMENTATION LIMITS 

The dratT standard sets out certain minimum 'translation Linus' which a 
conforming compiler nnusi cope with; you should be aware of these if you 
are portina applications to other compilers. A summary is given here. The 
'mem' limit indicates thm no limit is imposed other than that of available 
memory. 


Pew ripe ion Requirement 

Archimedes C 

Nesting levels of compound statements arid 

i tern i icrn/sc led > m cOn t ml -1 me cure s 

15 

mem 

Nesting level- of conditional compilation 

6 

mem 

Declarators modifying a basic type 

12 

mem 

Hx] 1 resioro nested by parenth^'^t^ 

12? 

mem 

S Eg nit sea nr characters 

- in internal identifiers and in aero name? 

31 

256 

- in c sternal identifier* 

6 

256 

External identifiers in one source file 

$11 

mem 

Identifiers with block scopL in one block 

127 

mem 

Macro identifier? in one source tile 

1024 

mem 

Parameters in one hint lion Jefininon/call 

31 

50 

Parameters m one macro definirion/invocation 

31 

mem 

Characters in l>oc logical source line 

509 

no limit 

Character- in a string literal 

509 

mem 

Ryles itt A Single .vCl 

32767 

mem 

Nesting levels for included files 

6 

mem 

Case labels in a sw:: :r. statement 

255 

mem 

:ic >?x in -registered functions 

32 

33 


30 
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Tli is chapter dbc-Usses aspects of the compiler which aren h E defined hy the 
ANSI draft standard, hut arc implementation-defined and must he 
documented. 

Appendix A.6 of the draft standard culled* together LnldraHtlon about 
portability issuer section A.6.3 lists those points which arc implementation 
defined, and directs that each implementation dial I document ir? behaviour 
in each nt the areas listed. Thi- chapter corresponds to appendix A-tbh 
answering the points listed in the appendix, under the same headings and in 
the same order. 


ENVIRONMENT (A.6.3.I) 


* Arguments to r^inO arc the wolds of The command line, delimited 
spaces. 

* The -nmdiird input, output unJ error streams, sr.din, stdout, and stderr 
can be redirected at runtime in the following way. For example, if copy is 
a compiled and linked program which simply copies the standard input to 
the standard output, the following line: 

*copy { < Inflie \ 

runs the program, redirecting stdin to the file ir file. Note that 
*copy 1 > out file \ 

redirects both stdout and st derr to the file out f i le; it is not possible 
to redirect st derr alone, 

* CommanJ-Une arguments redirecting stdin or atderut Jo not appear in 
rhe list of arguments to main () - 

* For full details <'l redirection in Anhur. see the Archimedes P*..igrammer's 
Reference Maraud, volume 1. 


IDENTIFIERS (A.6,3.2) 


* 256 characters are significant in identifiers without external linkage, 
i, Allowed characters are letters. digits,, and underscores.) 

* 256 characters are significant in identifiers wirh cxu'rnal linkage (Allowed 
characters arc lettcn, digits and underscores.) 

* Case distinct inns are significant in identifier* with external linkage. 

CHARACTERS (A.6.3.3) 

The character* in rhe wnjtec character set arc to 1?C 8859-1 (Latin 
Alphabet), a superset of the standard ASCI! character set. The printable 
characters are thr^e in the range 32 in 126 and 160 to Ii5. All printable 
characters may appeat in siring or character constants, and in comments. 


* The execution character -et is identical to the Source character *et. 

* There arc lour -liar* in an i nt. The byres are ordered from lean 
significant at the lowest address to most significfitit at rhe highesr address 

* There are eight bits in a character in the execution character *er, 1 he bits are 
ordered .such that the leftmost bit \- most significant. 

* Charuuer- or the source Lharvurei , ( -i m ormg literal and character 
constant* map identically inn‘ character*. m the execution character set 

* A character constant containing more than one character has the type int. 

Up to four characters of the constant are represented in the integer value. 
The first character contained in the constant occupies the lowest-addressed 
byte of the integer value, up to three following characters arc placed at 
ascending addre^cs Unused bytes arc filled with the NUL character. This 
is not portable. 

* A 'plain' chatr is treated as unsigned. 


}I 
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* Escape code* are; 


Escape sequence 

Char value 

Description 

\ a 

7 

Attention (bell) 

\b 

$ 

Backspace 

\f 

12 

Form fees! 

\n 

10 

Newline 

\r 

13 

Carriage return 

\t 

y 

Tab 

\ V 

u 

Vertical tab 

\ xnr 

tin 

ASCII code in hexadecimal 

\rtnn 

nun 

ASCI! code in octal 


INTEGERS!A.60.4 > 

The represent suon■- nnJ ser. of values of the integral types have been ser 

inir above in Impiefninfotfon dermis. Dam elements, Note also that: 

* "five result oi converting an integer tc \ shorter signed integer, ii the value 
cannot be represented, is a? it the bits in the ^rigifld vh|u£ which cannot be 
represented in the final value were masked .rii, and the resulting Integer 
sign--extended. The same applies when you convert an unsigned integer to .1 
signed integer of equal length, 

* Bitwise operations on signed integers yield the expected result given two’s 
complement representation- No sign extension takes place 

■ The sign of the remainder on image- division is the same as defined for the 

functi on dlv (J - 

* Right shift operations on signed integral types are arithmetic, 

FLOATING POINT (A.6.3.5) 

The representations and ranges of values of the floating poinr types have 
been given above in Implementation details, Data vie men tv Note dso ihftT: 


When a floating point number is converted m a shorter floating point one, it 
is rounded to the nearest re present a hie number. 


* The properties of floating point arithmetic accord with IEEE 7^4- 

ARRAVS AND POINTERS (A-63*6) 

Tint- ANSI draft standard specifies three areas in which rhe behaviour of 
arrays and piuniats must be dtxumentedl The points to note are; 

* The type $ i - 2 &_ c is defined ait -jn s 1 ^ned int, 

* Casting pointers to integers and ejee-versa involve*. no ^hangc of 
representation, Thus any integer obtained by casting front a pointer will be 
positive, 

* The type ptrd.: f f_t is defined as (signed) irit, 

REGISTERS (A.6.3,7) 

tn the Acorn C compiler„ you can declare up to six objects as having the 
storage class register. The vabd types arc; 

* any integer type 

* any pointer type 

* any structure type which contains only bitfields and which is no mote than 
one word tong. 

Note that other variables, not declared as register. may he held in 
registers for extended periods, .md that register variables may be held 
m memory for some periods. 


34 
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STRUCTURES. UNIONS AND BIT-FIELDS(AATH) 

The Acorn C compiler handles structures in (he following way: 

* When a member of a union is accessed using a member of a different type, 
cho resulting value can be predicted from the representation iff the original 
type, No error is given. 

* Structure*. are aligned on word boundaries Charterers are aliened in bytes, 
shorts on even numbered byte boundaries and all other lypes. except 
bitfields, .ire aligned on word boundaries. Bitfields are parrs of incs, 
themselves aligned on Word boundaries. 

* A ’plain' bitfield (declared as int} is Treated as unsigned int- 

* A bitfield which du-es not lit into the space remaining in an i :. r is placed in 
the next int, 

* The order of allocation of bitfields within . r.> b Mich char the first field 

specified occupies rhe least significant bit* *'f the word 

* Hit fields Jo not straddle storage unit fint) boundaries 

DECLARATORS (A.6.3.9) 

The number of declarators that may modify a basic type is limited only by 
available memory. 

STATEMENTS! A AT 10) 

The number nf :a?r values in a svrtch statement is limits! only by 


memory, 


PRE-PROCESSING DIRECTIVES <A.6.3.11) 


* A single-character character constant in a pre-proccsssr directive cannot have 
a negative value. 

* The standard header tiles arc cuntanlql within the compiler itself. The 
mechanism tor translating the standard suffix mechanism to an infix notation 
a described in Running the Compiler. Naming enmentionj. 

* Quoted names for includable source tiles arc supported- The rules inr 
ditectory searching are given in Running the CompflcT. Controlling the pre- 
processor. 

* The recognized tpragma directive .md 'heir meaning are described in 
♦Pragma dtretiftes. 

LIBRARY FUNCTIONS (A.63A2) 

When using hhrury functions in the Acorn C compiler, note the following 
points: 

* .The macro NULL expands fn rht- integer constant 0. 

■ If a program redefines a reserved external identifier, then an error may 
occur when the program ls linked with the standard libraries, li it is nor 
linked with standard libraries no error will he detected 

* The assert i I fuocrkm prints the following message- 

* TT assertion: failed: expression, f He iiienumg, line line- 
number 

and then calls the function abort i ) * 


The functions: 



isalnum I) 
isa 1 pha \) 
iscntr1 () 
iglowerfj 
iSprint I ) 
isupper {) 
ispunct l ) 
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usually test only tor character whose values arc in the range 0 to 3 27 
(inclusive! Characters with values greyer ih;tn J27 return a result of Q for 
all of these functions, except tsent s . ! ) which returns neuwero for 0 to 32 
(excluding \n, \ r, \v and Vt) and i2-S to 2 55. 


After the call set locale [LC_CTYFE r H ISO®3 5 1 IH I the following 

rules Apply for characters: 


0 to 31 except via, \ r t \v and \t are control characters 
123 to 159 are control characters, 

192 to 22 5 eiuepi 215 are upper case 
224 to 25 5 except 247 are lower case 
3 60 to 19 3, and 215 and 247 are punctuation 

Tht‘ results returned by the functions reflect this. 

* The mathematical functions return rhe following values on domain errors; 

Function Condi lion Returned value 


109 lx) 
loglO (x) 
sqrt (Jt) 
atanZ (x f y) 
asin [xj 
acos fxl 


x <» 0 
x <■ D 
x < D 
x - y =? D 
aba(x) >" 1 
abs <x) >= 1 


-KUSE_VAL 
-KUGt_VAL 
-HUEE_VAL 
0,0 
Fl/2 
0.0 


Where -HUGE 7AL is written above, a number is returned which ss defined 
in the header h.fnatfr. Consult the err no variable for the error number, 
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The mathematical functions Jo not set err no on underflow range errors. 
The set jffip < J function may he tailed in any expression context,. 

The ser of signals for the signal ( ) function is as follows' 


SIGAERT 

5IGFPE 

SIGILL 

5IGINT 

5IG5EGV 

5IGTERM 

3IGSTAK 


Abort 

Arithmetic exception 
Illegal instruction 
Attention request from user 
Bed. memory access 
Termination request 
Stack overflow 


The default handling of all iht signals recognised is to prim a suitable 
message followed by a stack back irate. This detauh behaviour applies at 
program startup- 

Hie i iiSt line of a text stream does no; require ?j fimmiiring newline 
character. 


Test lines consisting solely of space characters followed by a newline 
character are read back exacth as written. 

No NUI characters arc appended to j binary output stream, 

File buffering is performed as defined in the dr.nt standard {section T9.3), 

A re rt> length file does exist. 

The validity of file n.imeiy is delined by the host computer’s filing .system. 

The lame file can he •.«!••-n mans times for reading, and once for writing or 
updating. A file canrun however he open for reading on one stream and fnr 
wnring or updating on another 



k TANDARD IMPLEMENTA'! ION 
DEFINITION 


* Note also rhe following point* aboui Library t'uncrions: 


remove < i Cannot remove an dperi file. 

rename O The effect of catling rhe rename i ) funetion when the new 
name already exist* Ls dependent nn rhe hcrti tiling system. 
Nor all renames are valid: examples .jI invalid rt'nftiTseH 
tficluiic {”net: f ilel "net.: S . f ±1^2") .ind 

("nst: f ilel", ,r adf s: f i Le2“ ). 


fprint f (} Prints ^.p arguments in hex :*dcu mill format as if a precision 

of S had been specified, [f the varumi form is ideetcd. the 
number is preceded by the ch a Mirer 3, 


to can. f (] Treat* ■ p arguments identically to * x arguments. 

fa can f t) Always treats the Lliaracrer - in a % [ argument a* a literal 

character. 



ftelln 

Never reports failure 



perror (} 

Oerter^Te* the r allowing messages: 



Error: 

Message: 



0 

No error (errno » 01 


— 

ED OK 

EDOM - function argument out of 

range 


E RANGE 

Erange - function result not 


■— 

ESIGNUM 

representable 

ESIGNUM ~ illegal signal number 

to 



signal(] oi raise [) 



others 

Error cone number has no associated: 

—* 


message 



abort (j Ck«es all open files, and deletes all temporary files* 
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getenv {) 


system() 

st rcmp () etc 

atterror () 

clack () 

t in* (J 
setlocale ( ! 


Returns the value of the named Arthur Environmental 
variable, or NLILL if the variable bad rui value 
egroot = getenv ( H C$libroot"J ; 

if {root NULL} root = '*$ .an», elib"; 

See the chapter Calling other programs from C far a 
discussion of rht use of rhl*. Junction. 

Hie value returned by the memory- and nftng-cumpamon 
Junctions is in the ranRe - to -+H >T The value is negative 
if and only if the first string is lexically than the 
-eLunJ For example, suppose SI and SZ differ tlrst in the 
third character, Then srremp tSCSZKO irt Sl|2j<s2I2j. 

The emtoi message* given by this, function are iJtnricul to 
those six cn In the l : n r t i function. 

Return- the time taken by the program since its invocarton, 

. 1 ?- indicated by the host'- ope rat mg syiuem. 

Retumi. the duress me m seconds past i Jan-1970- 

QnEy has the standard LC_ macro? defined rmr it. The 
function call set: Locals (LC_CTYFE j. 41 IS08859- 1") 
alters the behaviour of the cty:e. h iuncrions, as described 
m the section CHARACTERS i A.6..1 Jf above. 


Local time iones and Daylight Saving TLitne are nor implemented The 
values returned will always indicate that the information is not available 
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To use Arthuriib functions, their Jeu Larai k*ns must he inserted in the cider's 
codr by means of a #include lint- Ah example, here ts the ‘hello 
world' program again, here using the p o da ( ) function to change screen 
mode: 

#include <stdio.h> 

* include <Arthur.b> 
int main() 
i 

mode f 7 }; 

printf ( "Hello world! \r, H j ; 
return Of 

J 

When the above program is cumpild and linked, the -arth’jr option has 
to be used: 

cc -arthur hello 

This cause* the linker to use the artnui lit librae tn addition to the usual 
ana i lib une. 


Because it as quite possible tor the names of the functions and variables 
declared in h.arthur to dash with other iden Ethers used in a prog man, a 
facility exists to enable an alternative set of name:. to he uiyeti These named 
art longer, hur are less likely to dash. 

It the m icro symbol AE 7 H'JF 'fEK KAMEc is defined before rhe Arthur 
header file is induded, then ill the names documented in this chapter must 
he prefixed hy ar ' before they can he used. Here is yet another version 
of the hello program using rhu method: 


#define ARTgtm_NEW_NAMES 
ft include <stdio.b> 
ft include <Arthur,h> 
int mairtO 

airt_mode (7) i 

print* ("Hello world I \n HI ) ; 
return 0; 

I 

An alternative way of achieving the same effect as the # define line above 
would be eo use the Command line option -I. ARTHUR NEW _NAMES- 

GENERAL ARTHURLIB FUNCTIONS 

These functions deal with general E/O tea cures of Arthur, including 
graphics sound and keyboard En general their fimcrionaliry emulates chat 
of similarly 1 named BASIC keywords. Brief descriptions arc given below, 
hut you are recommended to refer to the BASIC keyword section of the 
User Guide for comprehensive descriptions. 

Functions such .is os file 1 ) are essentially those- described in detail in the 
Anitur Prngrfliainer'j fte/rrence Manual. Any C structures referred to arc 
defined in the Arthur header fife < A 11 T u r ,a> tie 
$ . axm. cl ab. h . Art hut 1 En the function declarations, the AN Si 
prototype facility to give names as well as types to argument^ i> u^cd- This 
makes the argument*’ use a little mote stlf-cKplanatory. 

St recti calls 

void circle i int x, :nt y , int rad) ; - Draws a circular outline 
with centre at co-ordinate* (x.y) with radius rad. Equivalent to SWI 
"5 Plot with R-.‘=4 R I *x, R2»y followed by n SWI OS Ploi with 
RG=Cbc95„ Rl^rad+x and R1 -y 

void cl rclef ill (int x, int y,int tad) Draws a solid clrcJei* 
Arguments as above. Equivalents as above hut R0= i 0x9D l m the second call. 


4 1 
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void c i g (void) ; - Clwrs graphics window to the graphics background 
colour. Equivalent to SW| OSJWr itel+QxlQ.. 

void els (void) t - Clears text wtndOT to rht text haek^round colour. 

Equ i vale m to SiW I OS _W r it a I + 0 x 0 c - 

void colour lint coi) ; - Sets text foreground/back ground colour ro 
coi- Equivalent to SW1 OS _Wr it el* 0*12 followed by SW3 IS Write: 
with RO ■col, 

void cursor < i nt type) ; - Alter? cursor appearance The argument 
has the following meanings: 

Type Meaning 

0 Nude cursor 

1 Show' cursor 

2 Steady cursor 

3 Bashing cursor 

Equivalent to the G£_ HxiteC sequence Oxl7,i.tyre,0,0,0,0,QA0* 

void draw i int x H int y) ; - Draws a line to the specified absolute 
coordinates. Equivalent toSWI - 3 F i ot with RO fc S, Ri *x and R2*y. 

Void dxawby Unt 4 k r int dy) ; - Draws a line to coordinates 
specified rdarive ro current graphics cursor Equivalent ro S^l G5_P lot 
with RO-h Rl *dx iimi R2-dy 


void f ill f int x, int yj j - Flood-fill an area in the current 
foreground colour, scamne from (x,y). Equivalent to SWI OS F - :;v with 
R0=0xS5, Rl^x, and R2=y- 

void jcdI (int action* int col};- Set aerIon and colour for 
graphics foreground of background plotting. Equivalent to a bWl 
QS+Write 1+0x12 



followed by two 05_Wr l s eCs with RO*act Lon and RD-croi respectively 

void ^window(inr xl,int yl r int k 2,int y2 ) ; - Set up a 
graphics window- The bottom left and cop right comers of the wind:™ have 
the co-ordinate?, (xl,yl) and (>:2,y 2} respectively. Equivalent to the 
OS_Wr i ■ eC sequence QxiS,x. L;yL;x2;y2; where it semi*cokm implies the 
value i* sent as two bytes, low byte JirM- 

void mode ( i no ende] ; - Set screen me vie to mde. Equivalent to a SWI 
0S_Writel » 0x16 followed by a SWI OS_WriteC with RC'=ude- 

vci t move tint x, i nr. y \ ; - Move graphics cursor to absolute position 
lx,y). Equivalent to SWI OS_Plot with RO-4, Rl = y and R2 = y. 

void move by (int dx^int dy] Move graphics cursor to a position 
relative ro irs current position Equivalent to SWI ’S_Plot with R0=0, 
R|=*dx and R2=dy- 

void origin <in*. pin- y) ; Moves the graphics. arigin ti t absolute 
coordinates given. Equivalent to the 03_WriteC sequence Z' : ?,x;y', 

void nalsttefint i,int p, int r,int g r _nt b) ; - Physical to 
logical colour definition The arguments correspond to the live hr* - which 
follow an OS WriteC with RtMhtU. ie logical colour, physical colour red 
component, green *,nmpis-nenr and blue component- See the description of 
VDU 1^ in the User Lriiidc tor more details 

void plot (int type , in" x,im y ) r ‘ - Perform an operating system 
plot operation. This is equivalent to a SWI 0£_PLot with RC=type, Rl =x 
and R2-y. 

int pc int U ■ " . rr y 'i ; Find the logical dolour of the grip-hits 

pixel indicated h coordinate arguments. Equivalent To .* SWI 
OS ReadFc l r. r with R0«>:. R.1 = y and returning the value in R2 on exit 

:i r pos (void) ; Return rhe x coordinate of the texi cursor, Equivalent 
to a SWI OS_Byte with Rc^OxSi'a and returning the value in ftl on exit. 
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void rectangle (int x f Lnt y, int width,int height Plot a 
rectangular outline. The first iwn arguments give rile co-ordinates of the 
bottom left comet (for positive width and height). Equivalent to the 
following sequence of OS_E lots: 


RO 

EU 

R 2 

4 (Move abn) 

X 

Y 

3 (Line re]) 

width 

0 

l (Line re]) 

0 

height 

I (Line rel) 

-width 

0 

I (Line rel) 

0 

-height 


void rectanglefill(Int x,int y, int width,int height t; - 
Pint h holkl rectangle* Equivalent to a 5WI O r S_i . t wirh R0=4, Rl=x. 

RZ = v followed by a SWl QS_? lot with RQ-Oxfil, fU * width and 

Rl*helght. 

void st ringpri nt (mar - str) ; — Prints the imB'terminated string 
pointed to by atr on the currently enabled lArthur! 1 output oreams. 
Equivalent m a SWl OS_Wr 1 teC with FL0= - •. i 

void cab ( int x r ir.t y ) t - Position text cursor at (x,y) relative to the 
text window origin- Equivalent to a SWl Q5_Wr :tel~0xl f folUrwed by 
two calls to QSJrtnteC with R0=X dlnr y- 

void tint lint type, int tm ;i ; Set ^rey level of a colour. The 
first parameter gives the colour whose tint is to be set, as follows; 

Type Colour 

0 Text foreground 

1 Text background 

2 Graphics foreground 

3 Graphics, background 
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Equivalent to the OS_Writ.eC sequence Out 7,0s ll,type t tnt ,0,0,0,0,0,0, 

void vdu Unt ch) ; Sends ch to the current VDU streams. Equivalent 
to a SWE QSWriteG with R0=ch. 

void vduw (Int ch 2 ) ; - Sends ch£ as two characters to rhe current 
VDU streams in the order ch2 & Oxf f, {ch2 s Dxf fOO) >> 3. 
Equivalent ro two calls to SWE OS^WriteC. 

void vduq (int n, , , d ; - Sends n characters co the current VDU 
stream- integer arguments follow the first argument, and each or these is 
interpreted as a VDU byte. Equivalent to n calls to SV 1 OE_Wr iteC. 

l nt vpos (void) ; - Return the current text cursor y cu crdtnate. 

Keyboard/mouse calls 

Lnt let (” :d ; - Return a character code from the currently selected 
input stream. Equivalent to n SW1 0£_ReactC where R0 i* returned as the 
results 

int inkey (int delay) i - Return a character code fri>mi the input 
Stream nr keyboard, with timing Ventures taji BASIC !. Equivalent to a - 
OS_Byte with R0=0x81. RNiel ay * 0x1 0 0 and RZ-delay CxIC0. 
The return value is derived from Rl and R2 on exit. 

int mouse*(void ): 
int mousey(void ); 
int mouses{void )t 

Thtise three mou« functions return the position and button status of the 
mouse. Note that ihev should not he used with the WIMP functions 
described in rhe lies? section - the WIMP system provides special mouse 
function^- 
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Sound cait* 

int get beat (void) ; - Read current beat value- Equi valent to a SWI 
Sound QBeat with RG=>P on entry and using RO cm exit an the return value- 

i r.t ge + . Jr;e-iV3 (void) ; - Read beat counter cycle length. Equivalent to 
a SWI Sound_QBeat with RC'=-l& on entry and nuns RO on exit as the 
return value, 

int get: tempo (void) j - Read rare ar wbteh beat counter counts. 
Equivalent to a SWI Sotind_QTempo with R0=Q on entry and usme RO on 
exu as the return valuc- 

vcid set beats ( int beats) ; - Set hear counter cycle length to 
beats, so that it cycles from 0,, be at 3-1 ■ Equivalent to a SWI 
5ound_QBeat with RD^beats, 

void set_tstripe {int tempo) ; - Set rate hi which beat counter counts 
to tempo. Equivalent to a SWI Sound GTempo with RtV tempo, 

void sound tint chan, int amp, int pitch, int dur r int 
when) ; Make or schedule a sound. Arguments as BASIC, except that whan 
= -2 stti plies an unsynch remised sound event . If when ! = -2 then it is 
equivalent to a SW r l Sou nd_QSchedule- with RO»when, R1=0 and R2/RJ 
containing packed versions of the first four arguments. If wr.en = ihen nr 
is equivalent to a SWI SoundCont ro 1 with R0..R 1 set to the First four 
arguments, 

, void = o y n•:i_off r/oid) ; - 1 Deactivate sound system. Eq ui valent to a 
SWI Smmd_E rabble with f\0= 1. 

.vo:. a sound on (v . i. i r Activate sound system. Equivalent to a SWI 
Sound_£liable with R0=Z, 

void stereo ( 1 : 1 ", chan, int pos} Set stereo position for 
specified channel Equivalent to a SWI Sound Stereo with RG“tr.an, 
Rl«poa, 


void voices i in! vc*-s ) ; - Set number of active sound channel id 
vces (1, 2, 4 Of 8 ). Equivalent to a SWI Sound Configure with 
RO=veea and RS-R4=Q. 

VUactdtarieou** tails 

int adva 1 < int chan) ; - Rends data from an analogue pon or gives 
butler data. Equivalent to a SWI QSSyte with R0-0sfcl0 and Rl=-rhan. 

The > 3 ?t functions below provide access to the obvious operating system 
routines mdiuud by their names. For details of C structure mviiivd, see 
the \ . At chu* header hie. Error returns are as for the s« ix() function 
see below. 

error *osaros j reg_set ■ regs ) t - Perform a SWI 05_ Args. The 
arguments to the call ate found m the t -c_sot si rue i whose address is 
passed ti- art argument Only KC .R2 are used/altercd by the L.all, It there 
WSs no err,.r. NL'Ll j* returned, otherwise a pointer to an error structure ss 
rerumed- 

error *o;byte i reg_S*t - regg ) ; - Perform a SWI OS_By‘&- The 
arguments to the ceil are found in the reg^set struct whose address n 
passed as an argument. Only RLT.Ri! are useJ/akcrcd by the call. If there 
was no error, NULL is returned, otherwise a pointer to an error structure is 
returned. 

error ^osf i le (osf i lejbiocfc ■'phi i - Peribna a SWI OS_File. 
The arguments to the call are found in the os£ i ie^block struct whose 
address is passed as an argument- If there was no error, NULL is returned, 
otherwise a pointer to an error structure is returned:- 

error T Dsf ind ireg^set T regs) ; - Perform a laWl 0£_Find. The 
arguments to the call ore round in the reg_S£t struct whose address is 
passed as an argun&em Only RC..RZ are used/altered by the call. If there 
was no error, NULL is returned, otherwise a pointer to an error structure is 
returned- 
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esrror 'osgbpb (osgbpt_biock *p]b) i- Perform a SWI OSjGBPB< 

The argument to the call are found in the osgbpb_blQCK srmec whose 
address is passed as an argument It rhere was no error, NULL is returned, 
otherwise a pointer to an error structure is returned, 

error 'oswoidi int type, void T p.b ) ; - Perform a SWI OS Word. 

The type argument gives the OS_Word number, and the pb argument points 
to the free-formal OS_Word parameter block If there was no error, null is 
returned, otherwise a pointer to an or r :: structure is returned. 

unsigned rnd (unsigned seed!; - Return a BASIC-type random 
number, 

reg_3et awi fint SwiNutn, reg set *regsj This allows general 
access to operating system. SWI routines. This function does not trap any 
errors. Ir is passed arguments to indicate an action number and a pointer to 
an Input ’register set' {see h . Art hu r), It returns an output l regi&rer W. 
Equivalent to a SWI swi-V-tr with R(h.R9 set up from * rags and returning 
R0-R9 on exit. 

Knee rhat the input register set is passed by address whereas the result is 
returned as a structure value. Thus a typical call would Ionic, like thisi 

my Regs = s w i I OS_S W 3 Wu tribe r F r omS t r i ng, & sny Re gs I ; 

Note dlso dint at an error occurs, it is nor reported and there is no way CO 
delect it Ec is therefore only sensible to use thus call for SWls which will 
‘never* generate errors. 

error *EvriK(int BwiNrun, reg_Set *reqs I This allows general 

access to operating system SWI routines, as the previous one does, The 
arguments are the same a> Swi U , However, the ’X' form of SWI swiKuni 
Is used (by retting bit 17>, so that errors may he reported. If the SWI 
executes without an error, NULL is returned. If an error does occur, a 
pointer to men t structure is returned (see Arthur ,h for its fields), In 


either case, ■ rega is updated with the return values of R.0, R9. fSo in the 
case of an error, r egs-> 11 0] will also contain rhe error pointer) 


ARTHUR WIMP FUNCTIONS 

Applicatboru working under Arthur are provided with a comprehensive 
system of WIMP facilities. To use these, the relocatable modules 
WindfewHanager and Font Manager must he present {either resident in 
ROM or loaded into the relocatable module area). 

Writing applications to use the WIMP system is straightforward, provided 
you have read the Window manager chapter of the Programmer's 
Reference Manual. You are also recommended to refer to the Archimedes 
Re/erence Gtiilk The C interfaces to the WIMP functions are, therefore, 
listed Here wirh only brief descriptions 

The structures referred to m this ttguon are defined in < Arthur ,h>. The 
functions are listed below in order of the corresponding Wimp SWI 
number. 

All of the functions have an error + argument in -hov, where to pur error 
data if an error is generated. If there is no error, the errnum field of rhe 
error structure will be sen 1 no re rum. 

int w_initialise narror " ) ; - Close and delete all windows; 
returns wimp version number. 

int create wind (wind_block # H error M ; - Define (bur not 
display) a window, returning a window handle. 

int craate_icon (i con_bleck 41 , error *i ? - Add an icon 
definition ro that of .i window, returning an icon handle- 

void nelet e_wind ( int w handle, error M r ~ Delete (he 
window identified by w handle. 
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void delete icon (int w_handle, int l_h&ndls, error * ) i 
- Delete the iCotl identified by i_hand Le from the window specified by 
yj_nandle, 

void opet!_wind (open_tlock *, error *}; - Male a window^ 
appear on the screen, 

void clasewind (int w_hLsndle, error *) ; - Remove the window 
idenctiied by w handle from rhe list of active windows. 

int poll_wimp(int mask, univ_biock error *); - Ask 
what rn do nest, The mask gives the set of disallowed return codes. The 
code of the nest cask to perform is returned as the result, and the 
information pertaining to it is found in rhe univ 1 ? 

i n t red r a w_w indired r av_b lock *, error *); - Dmw a window 
outline and icons The window to be redrawn is indicated by the window 
handle m the redraw^ b lock The return value is false (.0) if (here arc no 
rectangles to be drawn. 

int update_wind {redraw block *, error *);-Return the 
visible portion of a window for updating. If the return is raise id), mure are 
no rectangles to update, 

int get rectangle* redraw block *, error * !•; - Gefdvtnext 
rectangle in a redraw Use. Returns false ii?1 if there are no more. 

void get wind_st ate lifet w_han£le, open_block *, error 
* t ; — Read rht current state of the window identified by w_handLe. State 
data is returned in apian ^block. 

void flet_icon_stateiistate_block *, error T i;- Set 
scme/all of nn icon’s flags The window and icon handler are held in 
lstate block. 


void get_LcQfi_^tate<iat*te_bloeJc 1 t error *>;- Return, in 
* i s tai: 0 _bicickH the definition of the icon identified by the icon handle 
field of * ist ate_block . 

void get point^infoEmouse block ” , error *) ; - Return dara 
about the mouse pointer. 

void drag^box(dragjslqe* *, error Start the wimp 

dragging a box. 

uo; d forcb_redraw(redraw_biock % error * \ ; - Force a 
reJi.ia- of an area of the screen. Only the first five ints in the 
r odr aw_block have sujnificance- 

void flet_caret_pos 1 caretJslock errot - Set the 
position iind size of t he text caret. 

void get._zar&r_pc3 ■. zaret_bl : ck ", error *);-Geithc 
position and sire of the test caret. 

void create menu(menu_block * f int f int, error *);- 
lnitLali.se a h pop up' menu struct me. 

void decode_memJ fm^nu_bloofe. univ^biock ' r textbuf * f 
vrror * ) i - Decode a menu selection, 

void whicb_icon{whichjb lock T , icon_list % error *>;- 
Look far icons with particular flag settings. 

v 3i :i set _ext>. nt i radraw_block * r error * ) ; - Alter the extent 
of a window's work area Only the window handle and first set of four 
coordinates are used from redraw^bioek. 

void set point. shape ipshape_block *, error M ; - Set oiv 
screen pointer'? sbiipc- 
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void open_terr,plate {char ‘name, error * ) ; -Open a file 
called name to allow load terpl ate ( ) to read a template from it. 

void elose_template fe r cor * I ; -Close the currently open 
template file. 

void leadLtemplate {romp_tiiock 'tb, error " ) ; - Load a 
window template from the open file into a buffer pointed to by tb - >bu f. 

TIils pointer to n buffer ran be cut to a twind_ block * ) and then u-sed 
to create a window usin^ create wind () . 






SSEMBLY LANGUAGE 
INTERFACE 


Objeu e code raodulef from, the A com C compiler can be linked with those 
produced by ObjAj»m t provided chat rhev observe rhe conventions of the 
ARM Procedure Coil Standard, (ObjAsm is a variant of the ARM 
assembler AA*m; AAsm generates directly executable code, wherrm 
ObjAsm generate?, code in a format suitable for linking. Ie tn Acorn Object 
Format .) 

This chapter gives a bric-s description of how to handle procedure entry and 
exit in assembly language in order to Interface to C, For details on A Asm 
and OhjAsiri syntax and AOF files, you should consuls 

ARM Assembler and Archimedes Programmer's Reference Manual, ARM 
PracedEire Call Standard, 

REGISTER NAMES 

The fallowing names rtre used in referring to ARM registers.; 


3l 

RO 

Argument l. aUo i nteper result 

a2 

Rl 

Argument 2 

a 3 

R2 

Argument 3 

a4 

R3 

Argument 4 

vl 

R4 

Register variable 

v2 

R5 

Register variable 

v3 

Rti 

Register variable 

v4 

R7 

Register variable 

vS 

R0 

Register variable 

v6 

R9 

Register variable 

fp 

RIO 

Frame pointer 

ip 

RU 

Used as temporary workspace 

sp 

Rt2 

Lower end of current Mack frame 

si 

R13 

Stack Lumi 

If 

R14 

Link address on calls, or workspace 

P c 

EU5 

Program counter and processor status 

fO 

FO 

Floating pomi result 

fl 

Ft 

Floating-point work register 


a 

n 

Roaring-poini work ref bier 

n 

F.1 

Flpating'poinc work register 

f4 

H 

Float mg-point register variable (muse be preserved) 

fS 

¥5 

Float mg-point register variable (must be preserved) 

f6 

F6 

Floating-point register variable (must he preserved) 

a 

F7 

Floatmg-pomr register variable (must be preserved) 


In this section, 'at r I means ar the location pointed to by the value in 
register t; 'at [ r^tn !' refers to the location pointed to by r+n. This 
accords. With A.Aim 1 '! syntax. 

REGISTER USAGE 

The following points should he noted about the contents of registers across 
function calls, 

* Calling a function (potentially) corrupts rhe argument registers al to a4, 
:p, _ r, and : -:. J The calling function should save the contents of any of 
these registers it may need, 

* Register ir is used at rhe time oE a function ciiil to pass rhe return link to 
the called function; it is nor necessarily preserved during vir hv the function 
call 

* The stack pointer at is not altered across the function call itself, though it 
may he adjusted rn the course of pushing arguments inside a function. The 
limit register si may change at any lime, hut should always represent a 
valid limit to the downward growth of sp. User axle will riot normally 
alter this register. 

* Register* vi ii,i find die frame pointer tt>, ufe expected to he preserved 
across function calls. The called procedure is responsible for saving and 
restoring the contents of any of these register* which it may need to use. 


% 
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CONTROL ARRIVAL 

At a procedure call, the convention is that the registers are used as follow® 

* al m h j i contain the first four arguments. 

* sp poems 10 the fifth argument; any further arguments will be located m 
succeeding words above [spin 

* fp points to a backtrace structure. 

* sp and si define a temporary workspace of at leao bvtc3 available w 
the procedure. 

* ir contains the value which should be restored into p c on exit from the 
catted procedure. 

* l c contains rhe entry iddress of the called procedure. 

* si contains a stack chunk handle, which is used by stack handling code to 
extend the stack in a non-comigmKj* manner 

PASSING ARGUMENTS 

All integral and pointer argument* are passed as 32-hit words. Flouting 
point 'float' arguments are )2-hr values, 'double -argument 64-bit v&tueH 
These follow the memory representation of the IEEE single <md double 
precision formats. 

Arguments are parsed n*- if hv the following sequence of operations: 


* Push each argument onto the stack. Iasi ftrgutfl&nr firtt. 

* Pop rhe first four words (or as many as were pushed, il fewer) of the 
arguments into registers a 1 to a4. 
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* Call the function, for example by the "branch with link' utsr ruction: 

BL /unctionname. 

In maiVy cast?? it is pcr&iihle to use a simpliiied sequence with the wimc 
effect (eg load three argument words into al-a 3). 

If more than four words of diguttiemis were passed, the railing procedure 
should adjust the stuck pointer after the call, incrementing it by four For 
each argument word which was pushed and not popped. 


RETURN LINK 


Qn return from a procedure, the registers arc set up as tollowii 

* £p, ap t si, vl to v6 and f A to f 7 have the same values that they contained 
at the procedure call. 

* Any result other than a Flouring point or a multi-word structure value is 
placed in register al. 

* A floating point result should be placed m register :'0, 

Structure values returned W function results are discussed below. 

STRUCTURE RESULTS 

A C function which returns i multi-word structure result i* treated in a 
slightly different manner from other functions hy the compiler A pointer to 
the location which should receive the result is added to the argument list as 
the first argument, so that a declaration such as the Following: 

s_type a function [ int a r int .fa, int c) 

{ 

s_type d; 

/* V 
return d; 

I 
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b in effect converted to this form- 

void afunction(s_type *p, int a* int b, int c) 

{ 

3 type d; 

/* ... */ 

*p = df 
return; 

I 

Any assembler-coded functions retumms structure results, nr calling such 
fum-nons, must conform to this model in order to interface successfully wirh 
object code from the C compiler. 

STORAGE OF VARIABLES 

The code produced by the C compiler uses procedure argument values from 
registers where posable: otherwise they are addressed relative to fp, as 
illustrated in Example below. 

Local variables, by contrast, arc always addresse i with positive offsets 
relative to sp. In code which alter- sp, this means that the offset lor the 
same variable wlLI differ twin place u< place. The reason for this approach 
is that il permit? rhe stack overflow procedure to recover by changing sp 
and si to point to a new stack segment ns necessary, 

FUNCTION WORKSPACE 

The values of sc and s 1 passed to ,i called function define an area of 
readable, writeable muirun available co the called function ns workspace. 

All words below [sc I and ,u nr above i s 1 , #-51 ? ] art guaranteed to he 

available ter reading and writing,, and the minimum allowed value of sp b 
s l-; c 6. Thas rhe minimum workspace available is 156 byre*. 

The C run-time system, in particular the stack extension code, requires up to 
.256 bytes of additional workspace to he left free. Accordingly, id I called 


functions which require no more than 256 bytes of workspace should resE thru 
Bp diyn run poirn to it location he low si, in other words that at least M2 
bytes remain, if rhe value in sc is less than that in si. The function should 
cal I the stack extension function xSstac?: over i low- Functions which 
need more than 25b bytes of workspace should amend the te.M. accordingly, 
and call x$stack overflowl. ns described below. The following 
examples illustrate a method ol performing this rest 


EXAMPLES 


Tire following fragments of assembler code illustrate the main points to 
consider in interfacing with the C compiler. Ii you u.int to examine the code 
produced hy the compiler in more detail for particular cases, you cun 
request an assembler listing with rht compiler option -S 

This is n function gag 7 which expect t two integer arguments .ind uses only 
one register vatiabie, vl. It calls another function f.ff£. 



AREA 

iC$$cCae|, CODE, PEADOWL ¥ 



IMP ORT 

1 tttt | 



EXPORT 

1 9999 i 


gggs 

DCB 

" qqqq 7 ' r C ; name o: i"uric T , 

O' terminated 


ALIGN 

?padded to word 

boundary 

gggy 

DCD 

Hi f f 00000o + gggy - gggx 




jdist, to start 

cf native 

;Function entry: save necessary rega, .and 

args- on 

stack 




qggg 

MOV 

ip, sp 



STMFD 

spE r [al| a2, vl f fp, ip, lr 

, pci 


SUB 

fp, ip, #4 ; points to saved pc 

; Test 

workspace siie 



CMP 5 

sp, si 



BLLT 

ixSstack overflow 1 


i Ka i n 

activity of function 



ADD 

vl, vl, 1 ?use a register variable 


BL 

Iffffl fcall another 

function 


W 
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CMP vl, 93 ;rely on reg* var* after 

C&X1 

J 

iReturn: place result in al f and restore saved 
registers 

MOV al, result 

LOME A fp, {vl, fp* sp* pc}* 

If a function will need more rh;m 1.5A hyres ot workspace, i.1 should replace 
the two-instruction workspace resr shown above with the following: 

SUB ip, sp, frn 

CMP ip, si 

BLLT |x$stack_overflowi| 

where n ts the number of bytes needed- Note that xSst ack_oyer f lowl 
must be called if more than 256 bytes of frame are needed- ip must 
contain sp_*needed, .as shown in the example above. 

A function which expects more than four words of arguments -hould store its 
argument* m the following manner: 

MOV ip, sp ;copy value of sp 

STKFD spl, jal, a2 t a 3* a4];save 4 words of args. 

STMFD sp], fvl, v2, Ep* ip* Ir* pc} 

,’save vl-v& needed 

SUB fp r ip r #20 ;fp points to saved pc 

CM?3 sp r si ;test workspace 

BLCC fcx^stac*; ove-rflow; 
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RRORS AND WARNINGS 


When compiling, the compiler can product 1 error nr warning merges nt' 
several degrees of importance, They arc: 

* Warning- 1 , indicating definite or possible offences against the draft ANSI 
Standard, 

* Non'serious errors which still allow code to be produced. 

* Serious errors which, may produce loss of Code. 

* Fatal errors which .stop the compiler from compiling, 

* System l-£toti which signal (aulrs in the compiler icself- 

Future releases of the compiler may distinguish further errors or produce 
slightly different forms of wording. 

The messages are listed alphabetically in each section 

warnings 

Warning messages indicate legal but curious C programs, offences against 
the ANSI draft, ot possibly unintended constructs. On detection of ,i 
warning condition, the compilei issues a warning message, ic enabled, then 
Continues compilation. 

* if define' macro ' xx' defined but not used 

* '$.* unnecessary for function or array yx 

This is a reminder that if xx is defined- as char arr [ IG J then xx has type 
char’. There is a similar reminder toi function names aho, Example: 

static char mesgtl - "helloW; 
tnt main U 
( 

char *p = ir,esg r ' /" mesg already has type char'' * 

* act uai type ’ xx' mismatches format ' x r 

A type error in a print f or scan f format string. Example: 


int i; 

printf<”^ s\d‘\ if; /* 4 s need char* not int */ 


ANSI * xx* trigraph ["or * x' found, - was this intended? 
This helps to avoid inadvertenr uye of ANSI trigraphs Example; 

printfi"Type 77/JJ: "f; /* 77/ is txigraph for W 

character sequence /* inside comment - error? 

You cannot nest com menu tn C, Example: 

/* comment out func() far new... 

/* funcilJi returns a random number */ 
int f uec <1 void) 

{ 

return i; 

) 

*/ 

Dangling ’else 1 indicates possible errer 
This hints chat you mnv have" nu* j itintdn.cd your i is- and el Remember 
an else always icter* t. • the im^t recent un-matched if Use parentheses 
to avoid ambiguity. Example: 

if (.a) 
if fb) 

return li 
else if (c) 
return 2; 

else /* this belongs to the If (a}„ Or does it?*/ 

return 3s 
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Deprecated declaration of xxn - give arg types 

A feature of [he ANSI dratt standard is that argument typr* should he 
given in tunction declarations (prototypes) L Nt> arguments’ is indicated hr 
void. Example: 

extern int funci),;/* should have ’void' in the 
parentheses */ 

extern ''main 1 needs to be r int 4 function 

Thi> is a reminder lhat rn.mnt 1 \a expected to return an integer. Example: 

void mainl) 
i 


floating point overflow when folding 

This is typitulEv caused hv ;i division by iero in <t flowing point cnrwiant 

expression evaluated ai compile time. Example: 

^define Lim 1 
* define eps 0,01 

static float a = eps/ UI&-1 ) ; / ‘ lim-1 yields G *• 
floating to integral conversion failed 

A cast (possibly imp licit) of a floating point comtam to ,m integer railed at 
compile tirrtc- Examples 

static int i - (inti 1.0&20; * 3axint Is about leiQ * ■*' 

formal pafameter ' xx ' not declared - 'int' assumed 
The declarer urn of a function parameter is missing. Example: 

int func(a) 

/■a should be declared here or within the parentheses*/ 
i 


t-’ormat requires nn parameterSf but mm given 
Mismatch between i pr i nt f or scant' format siring and its other 
arguments, Example: 

pr incf ( ,r td r %d\n l \ 1) ; /* should be two inta */ 
function xx declared but not used 

The (static) identifier xx was declared but not used within the source tile, 
illegal format conversion ’%*' 

Indicates an illegal conversion implied by a print t or scanf format 
string, Example; 

printf I rt '$w\n H ,10); /* no such thing as */ 

implicit return in non-void function 
A non'void function may exit without using a return »tatemem, bur won't 
return n meaningful result, Example: 

int func(int a) 

i 

int b=$*L0f 

no return <expr> statement * 

! 


implicit return in non-void xx() 

As above. 

Incomplete format string 

A mistake in a ; i , fit f of sea jif format string. Example: 

print f ("Score was " t score) ; /* 2nd * should be 

*/ 
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* 1 in t xx()' -assumed - 'void 1 intended? 

The JcfVnirion of a fund km omits its return parameter type - ANSI defines 
the default ro he int + You should be explicit about ihe type, using void it 
the function doesn't return a result- Example: 

main 13 

I 


* inventing "extern int xxU;' 

The dec hi rat ion of a function is missing Example: 

printf("Type your name: "I; 

/* forgot to ffinclude Cstdio.h^ */ 

* lake! xx was defined but not used 

Examples 

errleb: exit (-1 If ' this point never referenced */ 

* no side effect in void context: f f' 

An expression which doe* not yield any side effect wa* evaluated; it will 
have no effect Lit rurwime,. Example 

a+bir 


* non-portable - not 1 char in f xx' 

AsMtrrutig character constants containing other than one character to an int 
may produce nmvportable nr^ulis. Example: 

static int ex itCode = *ABEX 1 ; 

■ non-value return in a non-void, function 

The expression wins omitted from Ji return statfiffifflE in a tunClion lA'hich 
wa.s defined with a non-void return type- Example: 


6? 


int funcdnt ay 

i 

int b*a # lOf 

return; /* no *isxpr> * / 

] 

omitting trailing '’■.C- 1 for ctiar(nn] 

The character array being equated ia n string is one character too short for 
the whole string, so the trailing zero u being omitted. Example: 

scacic char mesq[14l = "(C) 1938 Acorn\n" t / * needs 15 */ 

Re-de f inir ion of #define macro 

Redefining a macro can indicate a possible oversight 

Shift by nn illegal in ANSI C 

ANSI C on Is allow* shut- of between 0 anJ {the sis* of an int in bits). 
Constant sihdb outside df this range but between 5 2 and 255 (which arc 
acceptable to the ASJM hard ware) produce this message Shitrs outside the 
range 0 to 255 produce rhe next warning- Example- 

static int mask = 1<<32; f+ would give j anyway 

Shift by nn illegal - here treated as nn 
This is given for negative constant shifts nr shifts grocer than 255. The 
horrora byre of the number given is used, ie ir treated as ( unsigned 
char) nn. NB. negative shifts are nor created ,is positive shitrs in rhe other 
direction^ Example 

print f ("%d\n" r l«-2) ; 

1 short■ slower than h int" on this machine 

For speed you ire . i J vised to use ir.:s rather than shorts where possible- 

Tliis is hecau.se of the uverhr.tJ of performing implicit casrs from short to 
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l n t m expression evaluation, However, short s arc hn.3f the sire of i r ;r s, ■so 
arrays of shorts can he useful- Example: 

E 

Short i , j; / ' quicker to use ints */ 


* spurious >) around scalrr in:tia’iser 

Curly bracked ;uv only required arotmd .it rue cure nnJ array initialises. 
Example: 

static int i - MKTT_I \; /* don't need brackets */ 

* static xx declared but not osad 

A *rsck variable wks- JeclareJ tn a tile hut never used in it If is therefore 
redundant 

* 1 struct' tas 1 xx' not defined 

It possible rbr ,t sti . ■ mc to declared before The hxdy of the 
structure U defined^ ro allow for mutuallv referencing tmtciufes, This 
warning implies that the end of the; block containing the incomplete 
definition was encountered without the lull definition being given Example: 

l 

struct s; /* forward reference */ 

Struct t \ 

struct s *sp; ■ * reference to struct a * / 

int A; 

1 

/* forgot tc define struct s */ 

] 

Certain styles of advanced programming using 'Abstract Data Types' may 
generate this warning frequently in client modules which import 'opaque' 
types. 




Uneie fined macro 'xx T in if i f - treated as 0 


Unrecognised #pragma -x 
Unrecognised ttpragma (no f -') 

#pragma directives are of the farm 

(fpragma -id 

where x is a letter an d is an optional digit These messages warn against 
unknown letters and missing Example; 

#pragma stack check(0) /* from some other compiler '/ 

use of 'op* in condition context 

Warns of such possible errors as = and not =- m an i f or looping 
statements Example; 

if ta=b) { 


variable xx declared but not used 

This refer? go sin automatic variable which was declared at the -ran of a 
block but newt used wirhin char block It is therefore redundant Lsample: 

int func(int p> 

{ 

int a; /■ this is never used m i 

return p*100; 

} 

xx treated as »?ful in 32-bit Imp lenten tation 
Hi is am mi! if hao's complement arithmenric’s dependence cm 

assigning initialix e constants to unsigned intis, and in explains that int5 
and long ints are both 32 hits. 
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NON-SERIOUS ERRORS 

Tlicit' art errors which will allow 'working code ro he produced - they will 
jKii produce lo&a of code On detection of such on error the compiler issuer 
an error message,, if enabled, then Continues tompitaLion. 

■ ' f ' (not 1 i M s ; ' LiEit?s formal parameters 

Incorrect punctuation between function parameters- Example: 

extern int EuntiliJnt a; int r i f 

* "up 1 : cast between function and object pointer 
Casts, between tunction and object pointer- can he very dangerousl 

One possibly valid (but still very suspect) use h in casting an array of Int 
into which machine dxic hrti been loaded into a function pointer- Example: 

static int sncArray f 100 ] ? 

/*pointer to function returning void*/ 
typedef void { r pfv)(veld); 

f (pfv) mdArray) () j ■■'convert to fn type and apply ' / 

* 'op': implicit cast of non-G int to pointer 

Zero, equal to 4 MI'LL pointer, is the only int which C^n he legally 
implicitly cast to a pointer type. Example: 

l 

int i, *ip; 

ip = it / * only the constant int G can be 

implicitly cast to a pointer type * 


* 'op 1 : implicit cast of pointer to non^equa. got:ter 

An illegal implicit c&si h:s> been detected bewteen tw, different pointer 
types. The type caning must he made explicit to escape ihi* error. Example: 
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int 
char 
ip = 


*ips 
*c pi 

cp; ■ r differing pointer types V 


T op' : implicit cast of pointer to l int’ 

An Illegal in up lie it cjsf has been detected hpiweep an integer and a primer. 
Such casus must hr made explicitly, Example: 

{ 

int 1-, *ip; 

i = ip; /* pointer must be cast explicitly * / 

H -Jp' : implicit rac-t , f 1 XX 1 to ’ int * 

An lI legal implicit cast has been detected. 

’xe3131*1 f ai'ribut- fir 1 xx' ignored: rfhen address 
taken 

Addressed of register variables cannot be calculated. an address beiu^ 
taken, oi a variable with a register storage davs cause is that attribute to 
b* dropped. F-rt ample: 

{ 

register int i r "ipf 

Ip = Si; /* k forces i to lose its register 
attribute */ 


T imiorj' tsg 'xx' not d&fined 
See above 

<int> op <pointet> treated as <int> op { int) ^.pointer> 
W ams oT an illegal imp lieu east within an expression. Typically op is an 
operator which has no business hem# used on pointers anyway, such ^ *- 
Example: 
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int 1 , *ip; 

i - i I ip; /* bitwise^cr: On a pointer?] */ 


■ ^.pointer - :j op cint> treated zc (im h'paint^t^ :c < ini > 
A? above but with the operands the other way round. 

* ANSI C does not support 'long float* 

This used to be a synonym for double, but is rioi allowed in ANSI C 

* Array 'Dj found 

The mmimum subscript count allowed is I (.Remember thar the subscripts 
go from j , « n - i.) Example: 

static int a[£J; 

* assignment t 1 const,* ?bjet: *Jfx’ 

You can't .isssgn to objects declared as const Example 

{ 

const int ic = 42; /* Initials4tion ok * / 

±c = /* can * t change it new * / 


* comparison 'op' of pointer and int: 

litoral 0 (tor -- and !-} is the only legal case 
You cannot use the comparison operators on .in integer and pointer type As 
the message implies, you can only ^ heck lor ,t pointer being (not) equ.il to 
NOl.i. Unt 0). Example 

i 

int if jr *ip; 

j = i>ip; /* can't compare an int and a * int */ 
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Control character Quean found - ignored 

An uftr&Ctfgnifrtd character was found embedded in your source this could 
he file corruption, so hack up your sources! Mote that 'control code' means 
any non-whitespace, non-printable character. 

differing pointer types; 'xx p 

An ille-yii] unplicLT type cast was detected in a comparison operation 
between iwo pointers of different rypes. Example: 


1 

lot *ip? 
char 'cp; 

print f \ ,i %d\n M , ip^cp) ; /* can 1 ': compare Chese */ 
differing pointer types; * 

The two sub expressions of a : conditional expression operator were 
pointers to different type* Example: 

i 

int i f *ipp 
char *cp/ 

printf ("lp\ti n i 7 ip : cp); * can't have char * 

or int * */ 


Digit S or 5 found in octal number 

Octal (base 8) number? may only h&ve digtU up nj Example: 

static int i = OilB j /■* probably meant 017 7, ie Oxff */ 

formal name missing in function definition 

This error occurs when a comma in a function definition led the compiler to 

suspect a further formal parameter was going to follow, hut none dtd- 

Example: 
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int ajifit b F ] /' missing parameter */ 

f 


* function prototype formal 'xs‘ needs type or class * 
’int* assumed 

A formal parameter in a function prototype was nor given a type or class, tt 
needs at Least one of these (register being the only allowed class). 
Example: 

void f-URC(a); f w I mean int a or perhaps register a */ 

» function xx may not be initialised - assuming function 
pointer 

A function is nut a variable, so cannot be initialised* As an attempt to 
injnabse rx ha? been made, ttx i* treated as of type function *. Example: 

extern int func(void); 

static int fni) = fine; * the compiler will use 

static int - func; instead */ 

* illegal string escape ' \x ’ - treated as x 
Unrecognised string escape (\ followed by a character) found. 

The \ is ignored. Example; 

print f ("Sw"' ) p /* no such escape *7 

* junk at end of fax line - ignored 

The xx U cither else orendif. Thwe directives should not have anything 
following them on the line. Example: 

/* text after the #elae should be a comment. * 
if else if it isn't defined 
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linkage disagreement for ' xx' - treated as * xx % 

There was a linkage type disagreement for deetOTiant. eg a function was 
declared as extern then defined later in the file as static. Example: 

int fund {iflt a) i /* compiler assumes extern here * •■' 

static fund int a) /* but told star in here */ 

{ 

Missing newline before EOF - inserted 

The 3 am line of the source file did not have ir* terminating end of line 

character, 

Missing type specification - 'int' assumed 
more than 4 chars In ' * T + ' 

■\ string constant of more chnn Mur characters cannot be assigned ro a 32 hit 
cnt. Example; 


int i 


'1234 5' , /* more than four chars *2 


no chars in character constant T1 

At leat one character should appear tn a character constant- The empty 
constant in taken as ieio. Example: 

I 

int i = p p ;; /* less than one char “= '\0 r */ 

Omitted <type> before formal declarator - 'int 1 assumed 
This is given tn a formal parameter declaration where a type modifier is 
given hut no base type. Example: 

Int funcI *al; /* a is a pointer, but to what? +/ 
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parentheses (..) inserted around expression following 

' QP' 

Parentheses were nor preseni when needed re- avoid ambiguity. 

return <expr> illegal. for void function 
A function decided m void moat nm return with m expression. Example 

void a(void) 

I 

return 0 t 


size of ‘void* required - treated as l 

This indicate^ an attempt to do pointer arithmetic on a void *, probably 

indicating an error. Examples 

{ 

void *vp,* 

vp++; /+ how many bytes to increment by ? */ 

size of a [T array required ~ treated as fl] 

If an array i$ declared as having an empty fir^t subscript the compiler 
cannot calculate the array** size. It therefore assumes The first subscript 
limit to be t if necessary. This is unlikely to he helpful. 

extern int arrayL] f1D]; 

static int 3 = sizeof {array) ; ■'* can't determine this* 

size of function required - treated as size of pointer 
The compiler tannor know the sise of a function a: compile time, so instead 
ir uses the sl*e of a ("Ml. Example; 

extern int funcfvoidj 1 ; 
int main{void! 


int i = s i zeo f f fiinc) ; 


( 


sizeof <bit field> illegal - sizedfinti assumed 
Bitfield* do nor necessarily occupy an integral miTtfbvr of bytes hut they are 
always parts of an int, so the size of An ini is used instead, Example: 

struct s [ 

int exp % Bi 
int mant ; 23; 
int s ; It 
)t 

int main(void) 

{ 

S t rnet s s t ; 

int i =■ si zeo f t St .exp] ; /* can't obtain this in 

bytes */ 


Small {single precision) floating value converted to 

0.0 

Small floating point value converted to 0*0 

A floating point constant was so small that jit had to be converted to 0,0. 

Example: 

static float f = l.OOOle-38 - 1.0e-38; /* l$~4Z top 

small for 
float */ 


Spurious fell: i rnored 
spurious #else ignored 
Spurious 3endtf ignored 

One of fhe>ie three direct iv r es was encountered oilttide of any 4 : £ or 
#ifi£tef scope, Example: 
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sif defined sym 
ffendif 

6 els* 1 /* this on.e iE spurious */ 


struct component xx may not be function - assuming 
function pointer 

A va riable such as a structure component cannot be dec bred Co have type 
function, only function *- Example: 

struct S i| 

int fn O; /* compiler will use int i*tn) [}; */ 
char c; 

D 

type cr class needed (except tn function definition} - 
int assumed 

You can't declare a function with neither a return type nor a storage class. 
One ot these must be present. Example: 

funcivoidf; f w need, eg, Int or static */ 

Undeclared fiatna, inventing 1 extern int xx* 

The name xr was undeclared, so the ANSI default type ext ern int was 
used. Example; 

int main(void) £ 

int i = j; / " j has not been previously declared*/ 


variable xx cay riot be function - assuming function 
pointer 

A variable cannot be declared to h.ivc type function, only function, *. 
Examp lei 


in.t main{void) 

f 

auto void in (void); /* treated as void 
{*fn){void); 


SERIOUS ERRORS 

These arc error* which will probably cause loss of generated aide. On 
dtreenun ot such an error, an error message is issued, and compilation stops, 
The compiler will attempt to continue and produce further diagnostic 
messages, which arc sometimes useful, but will delete the partly produced 
object file. 

* terror tnccutitered 

Source in ten r tonally producing .in emu with a l^rroi directive. Example: 
#1 1 CHASi_BIT ■= B 

terror This program needs e-gbt-bit characters 
tendif 

* * include file n xjr" wouldn't open 

* #inciude file <x:<> wouidn 1 1 open 

Probably caused by a spelling mistake m the Nle name. Example: 

H include <stdef ,h> / * missed Out a ' d 1 */ 

* 'hh*. 1 must have exactly 3 dots 

This is caused hv a rmsr.'nke in a function prototype where a variable number 
of arguments is specified. Ex amp lei 

extern int printf[const char ^format, .,,, )i J* one . too 

many*/ 


SO 
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■ 1 { 1 of function body expected - found ' xx* 

Thii is pttxfuced when the first character aftcr rhe formal p^mmerer 
dec i a rations of a function is not rhe ^ of the tune tie in hojy- Example: 

int func(a|i 
int a? 

if (a) -* * /* omitted the \ */ 

* ' \ r or -cident i l ie r> expected afr.^r ' xx\ but found 1 yy' 
\.y is typically struct or uni on, which muse he followed either hy the rag 
identifier or the open brace of the field list Example: 

struct * f red; /* Missed out the tan id */ 

* 'm' variables may not bo initialised 

* ’op'r oast to ‘xx 1 illegal 

* ' op r : caat to non-equal ’Xx’ illegal 

* 'op T : illegal cast of 'xx" to pointer 

* ‘op"; illegal cast to 'xx 1 

These errors report vanous ilSegal casting operations. Examples i 

struct s t 

int a,hr 

struct t j 

float ab; 

U 

int rr.ain (voidl 

t 

int i i 

struct S Si; 
struct t s2i 

h t = ’: cast to 11 int 4 illegal */ 
i = si; 

/* * = * t cast to non-equal 1 struc:' illegal *■ 


@1 


si * a2; 

/ + <CA3 t>: illegal cast of T struct’ to pointer */ 
i = * tint *) pi; 

/+ <cast>: illegal cast to ’int' */ 
i = (int) s2; 


'op': illegal use in pointer initialiser 

(Stark} pointer initialisers mint evaluate to a pointer or a pointer constant 

plus or minus an integer constant. This error is often accomplimed by others. 

Example: 

extern int count; 

static int *ip ■= fccount''^; 

xx may not have whitespace m it 

Tokens such a* [he compound alignment operators [ 1 etc) may not have 
embedded whitespace characters in them- Examples 

( 

int ij 

i + ; 4; f* space not allowed between + and = *f 


<command> expected but found a ’op’ 

This error occurs when a (binary) operator \> (bund where .i siatemem or 
side-effect expression would be expected. Example: 

if (aj /10; /* mis-placed ) perhaps? */ 


<**pression> expected but found 'op' 

Similar in above. An operator was found where an operand might 
reasonably he expected. Example; 

func(»10); /* missing left hand side of » V 
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* <identifiers expected but found 1 xx' in 'enu®' 
definition 

An unexpected token was found in the list of idennt’iers within rhe brace 1 ! of 
an enum definition Example; 

fenuxn colour {red, green, blue,;); /* spurious ; */ 

* \-=space> and \<tab> are invalid string escapes 

Use <apace> and \t respectively tor these characters iti strings ,ind 
character constants. Example; 

print f [ H \ Next?"); /■* Wo need for \ T / 

* \i must have 1 element to initialise scalar or ante 
When ,1 Miulur {integer or floating type) b initialised, the expression tlix:?, 
not have to be enclosed m braces, hut if they arc present, only one 
expression may be put her ween them. Example; 

static int i - {1,2 If /* which one to use? +/ 

■ Array size n,n illegal - 1 assumed 

Arrays hnvc a maximum dimension of Qxfffff f Example; 

static char diet[0x1000000]; /* Too big */ 

* attempt to apply a non-furction 

The function call operator ( ) iva* used after an expression which did not 
Vie Id a pointer to function type. Example; 


int i; 
if); 


* auto array T xx f may not be initialised 
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Automatic array? (defined in a function) may nor have initialisers. Only 
scat lc arrays may. Example; 

Ifft main() 

\ 

inn a[] - {1,2,4,8,16,32,64,128); 


Bit fields do not have addresses 

Bitfields do nor ncceswrily lie on addressable byte boundaries, so the & 
operator cannot tve used with them. Example; 

struct s l 

int hl,b2 ; 13; 

1; 


int main(void) 

( 

struct s si; 

abort *ap ■ &al.h2; /"can’t take & of bit field*/ 


Bit size nn Illegal - 1 assumed 

Bitfields hai^e a maximum permitted width oi 32 bits as they must fit in .1 
single integer Example: 

+ 

struct s t 

Int fl : ^10; /* This one is too big */ 
int f2 : 6; 

I; 


’break’ not in loop or switch - ignored 
A break statement was found which was not inside a for, while or dc 
loop or switch, This might he caused by an extra ), closing the statement 
prematurely. Example; 
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int Train (irit argcj 

{ 

if (argc ™ I) 
break; 


* 4 case 1 not in switch - ignored 

A case label was found which »a? nor irustic i switch statement. This 
might be caused by an extra !, dostnii the switch ?taiemenr premaTutrcly. 
Example: 

void fn(voidl 

l 

case ,+( : return; 


■ 'cant inue J net in loot - ignored 

A continue statement wa.s found which was not inside a tor, while or 
do loop. This might be caused by an extra », closing the switch statement 
prematurely- Example: 

while ice) [ 

if (dd) /* Intended a ( here */ 

error (}; 

} / + this closes the while */ 

if (eef 

continue; 

3 

* 1 default" cot in Switch - ignored 

A default label was found w hid. was not inside a switch statement 
This might he caused by an extra l, closing the sw itch statement 
prematurely- Example: 


switch fn) i 
case 0: 



return fn (nl; 
case It if (cc) 
return -1; 
else 
break; 

i /* spurious I closes the switch */ 
tie fault: 

error(); 


* Digit required after exponent marker 

A syntax error in a flouring point constant was found. Example: 

a = b*l.lej /* need [+/-]digits here "/ 

* duplicated case constant: .in 

The case label whose value is nn was found more than once (n <i switch 
statement Note that ml is printed h decimal integer regardless of the 
form the expression rook m the source Esampler 

switch tn> { 

case ' 1 : 

case * ': 


■ duplicate 'default' case ignored 

Two cast* in a single switch statement were I libelled defaul t. Example; 

switch (n) f 

defaulti 

default: 


} 
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duplicate definition of 'struct' tag 'xx' 

There sire duplicate definitiorut of ih? type struct xx U - ♦ I 
Example: 

struct s ( int i r j,rf; 
struct a ■; float a,b;p; 

duplicate definition Of 'union' tag 'xx' 

There ate duplicate definitions of the type union xx [ . , *} Example: 

union u first i; Char C'[^]; |; 
union u (double d; char 

duplicate declaration of *a~x' 

duplicate definition of *xx' 

duplicate definition of label xx -ignored 

These ,itl refer to vtmous rype* of duplicated definition. Examples: 

Static int i; 
void fnlvoid} 

( 

lab: 


l 

char 

lab: 

/* 

redeft nit Ion 

of 

lab ■/ 

if 

f* 

redefinition 

of 

i -/ 

int 

fn<) 

/* 

redefinition 

of 

ffn|> ‘ 


{ 

} 

duplicate type specification ot formal parameter 'xx' 
A formal function parameter had its type declared twice, once in the 
argument list and once after it Exampie: 


vcid £n{int ii 
Inc i; 
t 


/* this one is redundant w / 


EOF in comment 
EOF m string 
EOF in string escape 
EOF not newline after 

These all refer to unexpected occurrences at the end of iKe source tile. 

Expected cidentifier> after " xx' hut found ' xx‘ 

expected * xx* or 1 x* - inserted ' x* before ' yy* 
expected 'rx' - inserted before 1 yy* 

Thi“ typically occurs when t rerun nitnng semi-colon ha* hceu omitted 
heioTt u ■. (C’ounfnon amongst Pascal programmers) Aniichtr case n rhe 
onustjion a closing bracket «■! a parenthesised expression. Examples; 

int fndnt a, int to, Inc c) 

£ 

int d = e*{b+c; /* mis-sing ) *t 
return d /* missing } *f 

\ 


Expecting cdeclarator> or <type>, but f:und * xx r 

Jtx h typically a punctuation character found where a variable or function 

dccljiannn ot definition would be expected fat ihe top Ic-vd). Example: 

static int 1 = MAX;+i; /* spurious ; ends expression */ 

^goto 1 not followed by label - ignored 
Self explanatory- 
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Grossly over-long floating point number 
Only a certain number Jc cirn-.il digits arc needed to specify 3 floating 

point number to the -accuracy thill it can be stored to. Thu number of digits 
wus exceeded by art unreasonable anumnt. 

Grossly over-long hexadecimal constant 
A hexadecimal const, mi bas an excessive number of lead my iern^ not 
affecting its value, 

Grossly 0% h er^-long number 

A constant has an excessive number of leading zeros, noi affecting its value, 

Grossly ever-long string 

Hex digit needed after Ox or OX 

Hexdecimal constants must have ar least one digit from the set 0 . . $. a . . f , 
A, .F following the Ox. Examples 

int i = 3xq; /* illegal hex char */' 

Identifier { xx) found in < abstract rec i ar -'j ' or > 

The sizeo-f ( ? function and cast expressions require abstract declarators, ie 
types without an identifier name Tins ermf i- given when an identifier is 
found jn such a situation. Examples- 

t = (int j| ip; /* trying to cast tc integer */ 

1 = sizeejf (char str [ 10J i i * probably just mean 

sizeofjstr) */ 

illegal bit field type ’xx 1 - * int* assumed 
lnt (signed or unsigned) is rln- .mb valid birfield type in ANS1- 
conforming implementations, Example; 

Struct s ( char a ; 4; char b : A;\; 

illegal in #if expression xx 

illegal in case expression (ignored): xx 


■ illegal in constant expression: xx 

* illegal in floating typo initialiser: xx 

All of these errors occur when a constant is needed at compile tune hm a 
variable expression was found. 

* Illegal in 1-value: 'Qmjra' constant 'x.x' 

An incorrect attempt was made to assign to an an urn constant This could be 
caused by EiuS'SpeJling an enurr or variable identifier, Example 

eniiiii eo-1 \ red, green, blue-)# 
int fn(} 
f 

int read; 
red ■ 10,* 


* Illegal ,m the context of an 'XX* 

* Illegal in _v£lue: function or artsy ' xx' 

An incorrect attempt was made to avdgn to xx, where the object in question 
is not HSfrjgnAhfe (.An 1-value) You can’t, for example, assign m an array 
name or a function name. Examples: 


int a,b,e; 

a ? b ; e * 10; /* 3; can't yield 1-values. */ 
if la) /* use this instead */ 

b = 10; 

else 

c = 10; 


or, m the same c- ntext, 

* (a ? sb: *c> = 10 ; 


90 



E 


RRGRS AND WARNINGS 


* illegal in static integral type initialiser: xx 

A con st am was needed at corn pile rime hue a smEahle expression wasn't 
found, 

* Illegal types for operands : 'op' 

An operation was artempted using operands which are unsuitable for the 
operator in question. Examples: 

l 

st ruct jint a,b;) s; 
int U 

i = *s; /* can’t indirect through a struct */ 

s * s+s; f* can't add Strutts * / 


* Junk after #if <expras$ion> 

* Junk after ^include "xx’’ 

* Junk after ^include <xx> 

None of these directives -should have any other non-whitespace character 
following the expres&iun/fdename. Examp let 

# include <stdio.h> this isn’t allowed 

* label 1 xx‘ has not been set 

An attempt has been made to itse a label that has tier been declared in rhe 
current scope, after having been referenced m a goto statement* Example: 

int Ki-ain (void) 

\ 

goto and; 

\ 

* Misplaced "( 1 at top level - ignoring block 

• j blocks can unly occur within faction definitions. Example: 
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/* need a function name here */ 

{ 

int if 


Misplaced T else T ignored 

An else with no matching i T was found* Example: 

if (ccS /* should have used l } */ 

i - ij 
j -3; 

else 

k = 3f 


Missing #endif at EOF 

A # i f or * i f ::e f was >till iciive at end of the SOufCt hie. The^e directives 
muaT always he marched with a *ert:!±f- 

Missing ' 11 * in pre-processor command Line 
A line such an- * in elude "name ki& the second ,h mining. 

Missing ') 1 after xX(,. . on line nn 

The closing bracket (or comma separating rhe argument^ nf a macro call 
was omitted, Example: 

#defina rdch(p) (cfo=*p--;i 

i 

rdchtp /* missing ) */ 


Missing ox 'after ^define xx(.., 

One of the above characters was omitted after ;m identifier in the macro 
parameter list* Example: 


4define rdeh (p I eh - p p++; I 
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* Missing '<' or ■"' after (^include 

A Uinclude filename should he within either double quote? or angled 
brackets, 

* Missing identifier -after itdefine 

* Missing identifier after #ifdef 

■ Missing identifier after tundef 

Each of these directive?, should he followed by a valid C identifier. 
Example: 

#define £ at 

* Missing parameter name in ^define XX U- - 

No idcnrifter was found after a 1 , ' in a macro parameter list Example; 

*define rdcb(p,) jch**pf+;] 

* Missing hex digit(5) after \X 

The string escape \sc is intended to he used to insert ASCII coded 
characters in a srnng, but was incorrectly used here. It should be followed 
by between one and three hexadecimal digits- (On the present system, lI 
there are three digits following the ix, the first one is ignored.) Example: 

printf(”\xxx /")i /* probably meant " ■ \xxx/" * 

* No ')' after #it defined ( , < 

The def : r'ied operator expects an identifier, optionally enclosed within 

bracket*. Example; 

#if defined(debug 

* No identifier sfter *if defined 

See above. 
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* non static address r wjf f in pointer initialiser 

An attempt was made to t;ike the ^JJrew, erf an automatic variable in an 
express ion uned to ittflialift: a s i a r - - c pointer, bueh addresses are not 
known at tempi Ic-h me- Example: 

i 

int ijf 

static int *Ip = Si; /*&t not known to compiler*/ 


* Non-forma1 1 xx’ in parameter-type-spec■f■or 

A parameter name used to declare the parxtmeTL-T types did non actually 
oclue in the parameter list of the him non. Example; 

void fn(a) 

int 

t 


* Number nn too large for 32-bit implementation 

An integer constant was found which was rtw> large to fit m a U bn int. 
Example: 

static int mask = 0x800000000; /*0x800000Q0 intended?*/ 

* Overlarge floating point value retina 

■ Overiarge (single precision) floating point value found 
A floating point constant has been found which is so large thai It will nm hi 
m a floating point variable. Examples: 

float f - Ie4Q; /* largest Is approx Le38 for float */ 
double d ™ ledlQj i* and Le308 for double */ 

* guote ( 11 or ') inserted before newline 

Strings and character con*mnr> arc nut allowed to contain unescaped 
newline characters. Use \<nl > to allow strings to spriii lines, Example; 
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printf("Total - 

* re-using 'struct' tag 'xx' as 'union 1 tag 

There are conflicting definitions nf rhe type struct xx [, * * j ; and 
uni on xx i . „ . \ ; , Structure and union lags currently share the same 

namespace in C, although this nor actually necessary. Example: 

strudt s lint a,b; 1; 

union 5 (int a; double d;J; 

* re-using 'union' tag "xx 1 as 4 struct' tag 
As above 

* size of struct “xx 1 needed but not yet defined 

An uperation require* knowledge of rhe size of ihe struct, hut rim wa* nor 
defined- This error t, likely to Accompany others. Example: 


{ 

struct st 
struct s *sp; 
sp++; 


forward declaration "/ 

/* pointer to s */ 

'" need size for inc operation*/ 


* size of union ' xx' Headed but not yet defined 
See above. 

* storage class 'xx h Incompatible with 'xx' - ignored 

An attempt was made to declare a variable with conflicting storage classes. 
Example: 

{ 

static auto int i? /- contradiction in terms */ 
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storage class ' xx' not perTT.itted in content xx - 
Ignored 

An attempt wa* made TO declare a variable whose storage class conflicted 
with its position in the program. Examples: 

register int 1; /* can*t have top-level pegs */ 

void f n (a .1 

static int a; /* or static parameters */ 

i 

string initialiser longer thar: chat inn' 

An attempt was made to initialise a character array wnh a strinc longer than 
the array* Example; 

static char strtlO] - M 1,234 561890 1234 " ; 

stroot 1 xx 1 roust be defined for [static) variable 
declaration 

Before you can declare a static structure variable, that •irmctUR r ¥f e imusi 
have been defined. This is so the compiler know* how much storage no 
reserve for it- Example- 1 !; 

static struct a sly /* s not defined */ 

Struct t; 

static struct t t U /* t not defined */ 
struct/union ’xx* has no xx field 

The UelJ name used with it , or -> operator is not a valid »e tor the union 
or srj-uctiire type '.nr 1 being referenced. Example: 

struct s (int a, b ;\; 

i 

struct s si; 

sl,c * 3; f* no c field */ 
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* struct/uni on 'jcx' not yet defined - cannot be selected 
f ram 

The structure or union type used us rhe left: operand of a , or -> upeMtOf 
has not yet been defined so the field name* are not known. Example: 

1 

struct s si; 

si.a * 12 ; /* don "t know field names yet */ 


* Too few arguments to macro xi|,.. on l:ne nn 

* Too many arguments to macro xx ( . , . on line nn 

The number at arguments used in the invocation of a man 3 must match 
exactly the number used when it wan defined, Example; 

#define rdch <cti*p) while ((ch *p++y==>* "); 

rdch(ptrj; /* need ptr and ch */ 


* too many initialisers in {j for aggregate 

The list of constants in a static array or structure initialiser exceeded the 
number of elcmcins/fidds for the rype involved. Example: 

static int powers[B] - 10,1,2, 4 ,B,16,32,$4,128}; 

* Tqq many arguments In function call - ignored 

* type ' xx' inconsistent with * xx* 

* type disagreement for * xx' 

Conflicting types were encountered in function declaration {prototype) ant l 
its definition. Example: 
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void infirm); 


int fnfini a) 

{ 


typedef name used in expression context 

A typedef name was u*ed as a variable name. Example: 

typedef char flag; 


int i = flag; 

undefined struct/union ' xx* cannot be member 
A struct/union not already defined cannot be a member of another 
struct /uni ?n. In part mu Ear rhss means that a struct/union cannot be 
a member of itself - circular types arc not allowed. Example: 

struct sl { 

struct s2 type; /* s2 not defined yet */ 
int count; 


Unknown directive : 

The identifier following j n did not correspond to any of the recognised 
p re-processor directives- Example: 

#astn /* not .an ANSI directive */ 

wrong number of parameters to * xX* 

The function is was called with the wrong number of para meters, as 
defined by its pretype. Examples 


s*ze t strie-n (const char *3); 
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int i = strlen(str,j ); /* only see needed */ 

* Uninitialised static [j arrays illegal 

Stark i ] arrays must be initialised to allow the compiler to Je terming rheir 
St:e. Example: 

static char str[]f ■* * needs O initialiser */ 

* uri ion variable 1 xx* must htf ie£i ned for ( s ta1 1 c I 
variable- declaration 

Before you can declare a static union variable, chirr union type must have 
been defined- Example t 

static union u ul; /* compiler can't, ascertain ffise * 

* 'while F expected after ’do' - found 'xx r 

The syntax of the do srateroeni is do stoirtnent while (expression) - 
Example: 

do /+ should put these statements in {} w / 

1 = inputLine{3; 

err * processLlne<l>:/*finds err# not while 

V 

while (3err}f 


FATAL ERRORS 

These are causes for the compiler to give up compilation. Error messages 
are issued and the compiler stops. 

* Couldn’t create object file ’file 1 

The compiler was unable to open or write to the specified output code file, 
pethaps because It was locked or the o directory dotfc not exist. 

* macro args too long 
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Grossly over-long macro arguments 

■ macro expansion buffer overflow 
Grossly over-complicated macros were used. 


* wo score left 

out of store (in cc_alloc) 

The compiler has run out of memory - either shorten your souitr programs 
or free some RAM using rhe 4 UfJP LUG command. To do ibis, first check 
which modules are present in your machine by Typing 4 MODULES, If rhert 
is a module that you do nor currently need, you can release its space by 
typing 

w UNPLUG jnodulenajne 

It can later he restored using the ' RMRE INIT command, For further 
deiaiU, refer ro the section entitled MuduEea in the Archimeeki 
Programmers fie/erertce Manual, VnJ 2 . 

* Too many errors 

More rhan 100 serious errors weft detected 

* Too many file names 

An -iticm.pt was made ti < compile too many files ar . mce. 25 b the maximum 
that will be accepted. 

SYSTEM ERRORS 

There .ire some additional error messages that can be generated by the 
Compiler if it detects errors in the compiler itself, h is very unusual to 
encounter Hu- type of error. If you do, note the circumstances under which 
the error was caused and contact vour Atom dealer 
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This chapter discusses the differences apparent when the compiler is used 
in TCC mode- When Riven the -pee command tine flag, the C compiler 
will accept il^erketeyl Unix-compatible C. as defined hy the 
implemeirtanon of the Portable C Compiler and subject to the rest net ions 
which are noted below. 

In essence. PCC-style C is (Cermghan and Ritchie' C\ as defined in the book 
The C Pmgranunmg LarujuuJie. by B. Kcmughun atuE D Ritchie (K&Rh with 
it small number of extensions and clarifications of language features that 
the hook leaves undefined, 

LANGUAGE AND PRE-PROCESSOR COMPATIBILITY 


En -pcc mode, the Acorn C compiler accepts K&cR C , but it dises- not 
accept many of the old-style compatibility features, the use uJ which has 
been deprecated ,mj warned against for many years. Differences are listed 
briefly below: 

■ Compound assignment operators where the - sign corner first ate accepted 
(with a warning) bv some POCs. An example is = + instead erf ■+■ A com C 
does nor allow this ordering of the characters in the token 

* The =i sign before a static initialiser was nor required m some very old 
Ipre-KikR C) compilers. Acorn C does not support this syntH*. 

* The following, very peculiar, usage is found in some Unix tooh pre¬ 

dating Unix Version 7: 

struct lint a, it;}; 

double d; 

d. a = C; 
d.b = Ox....; 

This as accepted by Unix PUCs and mav cause problems when porting old 
tand badly writ ecu) code* 


temjfrts arc less strongly types chan is usual under PCQg, enuen n* a noti- 
K&R ey tendon m C. which has been standardised by ANSI somewhat 
differently from the usual FIX' ttnplemenration- The compiler warns of this 
when an enarn is encountered. 


cha e> are signed by default in -poc mode. 

In -pcc mode, the compiler permits thr use of the ANSI . 1 notation 
which signifies that a variable number lf (‘ formal arguments follow. 

With the exception of enutns, the compiler 1 '- type checking ■$ generallv 
^tricrer than PCCs - much more akin to hnr's, in fact- In writing the Acorn C 
compter, we have attempted ro smke a balance between generating too 
many warnings when compiling known, working code, and warning mf poor 
Of non-portable programming practices, Many FXJCs silently compile code 
which Has no chance of executing in just a slightIv dilfctcnt environment. 

We have med to he helpful to those who must port C among machines in 
which the following varies 

the order of bytes within a word fc.g little-endian ARM, VAX, Intel 
versus big-endian Motorola, EBMH701, 

the default size of i r,: (four bytes versus two byre* manv FC 
implementation id, 

the default size of pointers (not always the >SmC a- tnth 

whether values of type chat default to signed or unsigned char, 

rht- default handling of undefined and implementation-defined aspects 
of the C language. 

If the verbosity of cc -pcc is found undesirable then nil warning* can be 
turned off by usmp the -w command-line flag, 

The compiler's preprocessor is believed to be equivalent to Unix’s epp, 
except for the point* lifted below. Unfortunately, epp is only JetmeJ hy iii 



p 


CC COMPATIBILITY MODE 


implementation, and although equivalence has hern tested over a large 
body of Unix Source tntk\ cnmpktdy identical behaviour cannot be 
guaranteed- Some of the poinr* limed bebw only apply when the -E option 
is used with the ec command. 

There is a different treatment of whitespace sequence* (benign). 

^<nl> iii processed by cc -E r hut passed by epp (making lines longer 
than expected; cc -E only) 

Cpp breaks long lines at a token boundary; cc -E doesn’t (this may 
break line-sire cOfiatrainf-S when the source is tarer consumed by another 
pltigmm CC -E only). 

The production of I line "file" directives is different icq -E only). 

The handling of unrecognised it directives is different (this is mostly 
benign) 

Literal control characters cause cc ro issue a warning (but they are not 
ignored as they are in ANSI model 

The 'whitespace control characters' form-feed, carnage -return, and 
verricahrah are converted to newline. 

STANDARD HEADERS AND LIBRARY 

Use of the compiler in -pc: mode preclude-, neither the use ot the 
standard ANSI headers built in to the compiler nor the use of the nm-time 
library supplied with the C compiler 

Of course,, the AN!s| library does not contain the whole ot the Unis C 
library, but it does contain almost all the cnminonly used functions. Beware, 
however, thar some functions have different names, for example rhe A 1^51 
function strichrU is called t index i i under BSD Unix 


Also some functions have a slightly different definition For example, the 
ANSI sprint f {) returns the number of characters ‘printed 1 , whereas the 
BSD sprintt <) returns a pointer n> riu- start of the character buffer- (This 
does nor matter Li the function is used in a voi ci context, .i.i ns often the 
case.) Fortunately, the important functions such as print f ( ; , fprlntfO + 
em-L1k>g L) j st repy (), etc., are all identical 

Another hazard is rh.it the “standaid' definitions are sometimes in different 
'standard' places. For example, the A MSI si riot-hand! mg functions are 
defined in <str,. ng*h>, whereas the BSD si ring-handling (unctions are 
defined in <3 1 r i nqs , h >. 

Unless the user directs otherwise usm^ - i r the C compiler will attempt to 
satisfy references to, *ay, <stdic . h> from its m-storc filing system- Of 
course, ibis header is an ANSI header and is invalid m -s cc mode. 
However, the compiler is ;;ible 10 switch it*eli retnpirardy into ANSI mode 
when reading tn store headers, switching hack to -pcc mode for everything 
Hsc This behaviour cannot be exploited to use real ANSI header files; rhe 
cLimpffet can 1 mb dn it using rhe file? ir knows about (and for which the 
switch to ANSI mode is known to he harmless). 

Time functions an 1 very system-dependent, but this is well-known within the 
C community and doesn't usually constitute much of a problem m software 
written with portability in mind. 

Notwithstanding these problems, main simple program* will compile 
immediately using cc -pcc. 



ALLING OTHER 
PROGRAMS FROM C 


INTRODUCTION 

The C library prvcedutr system ( > provide the meani whereby a 
program can pa.-.* a command to the host system’s command line interpreter 
The romantics at" this art undefined by the draft ANSI standftrd- 

Archur distinguishes two binds of commands, which we can loosely term 
built-in command) and applications, These have different effects. The 
former always return tc their callers, the latter return In the previously set¬ 
up ‘exit hand Let' Because of these differences, system (> exhibits three 
kinds of behaviour. This is explained beb>w 

Appfi cations in Arthur are loaded at a fixed address- specified hy the 
application image. Normally, thL.- is the base of application workspace. 
0x8000- While executing, applications are tree to use stare between the 
base and end of application, workspace. The end is the value returned by 
SWl OS_GetEnv. They terminate with a call ofSWl OS Exit, which 
transfers control re the current exit haitdlct- 

When a C program makes the call system < "'c cm maud”) , the result 
depends an the type of command; 

* A built-in command will execute and return to the C program If then- was 
no error, system i ) returns 0, otherwnie it returns something non-0 (which 
may vary from one release rn another) 

* An. application will Load, possibly ovefwmthg the G pn gram, execute, then 
return through the exit handler. This is usttfllly set to the Arthur command 
mode, hue some applications such as Twin and BASIC's 'shell 1 library also 
set up exit handler*- The C program effectively loses contra! the moment ir 
does the system () - 

To provide finer control two variants of system ( ) are provided. It rhe 
argument to system ( l begins with CALLi and the callee is a built-in 
command or an application satisfying certain conditions ideuerrbed below) 



then return from system \) is guaranteed Similarly, ii the command string 
begins CHAIN: then there wit I be no return, even if the churned command is 
built-in. 

In order for an application to invoke other applications and have control 
return, ii t* necessary to: 

arrange that the invoking application occupies an address range clear of that 
required by the invoked application, 

vet rhe end of application workspace below the base of rhe invoking 
application* and 

set an exit handler sn rhaE rhe invoking application regains control when rhe 
invoked application exits. 

Note: It iv not p.issible to load Arthur modules from an Arthur application 
unless the relocatable module area (RMA) has been configured to he 
sufficiently laree Whereas loading modules from the Arthur command 
mode sueceed> because it can extend the RMA k rhi.s cannot be done it there 
is an active application. 

When the library function sys" ( ) is given an argument lining starting 
with the characters CALL:, it automatically perform* rhe second and third 
ut these tasks, before handing the remainder of the argument string to 
D£_CLI to execute- So the C program only has to worry about the first 
potnr, avoiding a clash of memory requirements. This can be solved in two 
ways; 

The invoking application can be linked to load i.tt a fixed high address- This 
is r.irhs ■ in flex il If. For example, selecting an address which will allow the 
application ro run on a range ol machines with differing memory sizes 
means wasting memory in rhe larger machines. 

The (relocatable) invoking application can re-load itself at the top o) 
available memory. This technique has the advantage of being more general 
than the fiirsr. 
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The invoking application can he linked to he (bad-time) relocatable, uiving 
the linker'^ -c^lccat able- flag Such an application will he traded at 
OxSODO if run directly, hue either the application itself can observe that it is 
running at too low art .i.kirL-^.s, .md refold itself -^uit-ihic distance Prom the 
top of memory, or one can ran a small bootstrap applies cion which loads 
the main application a suitable distance from rhe top of memory, 

(One might think that in the tir-t case, the image could he moved up from Jt^ 
current position to a suitable one. then re-entered UnfommiUclv, hy the 
time the image is entered the relocation ruble h-as been cverwrnten, so re¬ 
entering fails). 

Which of these methods is preferable depends principally on the sire of 
the application: the larger it is, rhe more attractive the boorstrap method. 

The code required is. much the same in both cases* and is illustrated bv a 
small CLI example lwhich u&ei the itlfnefotd method) below 

Note that, in this example, when the application is reloaded, its arguments 
start at a r gv \ 2 ] , not a rgv ; 1 ]: arijv f Q ) is if g c rt and arqv [ 11 is 
“<addxess>;", 

Although in this example the required heap site is a constant, the method is 
obviously adaptable to mote complicated values, for example H could u-e ft 
fixed proportion of available memory, or an amount determined by (some 
property of) the arguments, 

AN EXAMPLE PROGRAM USING system() 

The following example can be found on The distribution disc with rhe 
filename BawToCall* I: is a command line interpreter that reloads itself a 
fixed distance truru the end of store, then prompts for commands which are 
passed to Arthur tor execution via system (}. Any command - including 
the invocation of another application (eg the CLI itself)- can be executed, 
provided that there is enough memory. 


#include <ker nel* h> 

^include <stdio*h> 

#include <stdlib.h> 

#include ^-string * h> 

^include <ctype.h> 

t define GS^GetEnv 0x10 

#def ine MaxHeapSise i! 32* 1024} 

ttdetine LcadFi ] eUsi ngPathVariafcle Dxe 

static void CheckError{int status* 

{ 

it (status^- kernel ERROR* \ 

_kernel_oserror *err = _kernel_la3t_Pserrorf>; 
fprintf<stderr, "can't reload; *s\n", 

&ierr->errmess))f 

exit(1)f 

\ else if (statusl-i* \ 

fpr intf ^stderr, " ran 1 ':. reload\n" S ; 
exit (1>; 

1 

1 

static void SelfReload(char *namej 

{ 

/+ This procedure reloads the current application a 
distance celow the top f memory which all ours it a heap 
to be of size MaxHeapSiae, then enters it with the same 
arguments as it was given this time iand does not 
return *. 

Except: if the application is already at the right 
address, the procedure does nothing and returns* 

if the reload fails, in which case a message 
saying gc is produced and execution terminates** 
_kernel_swi_rega regsj 
int *heapptr “ fb&llQC'(4} ; 

_kernel_swi(OS GetEnv, &regs, ftregs); 

/* {No error possible? 



c 


AILING OTHER 
PROGRAMS FROM C 


* is our argument string 

* regs*r!1J is the top of available memory 
*/ 

if (Sint) heapptr < rjgs,r11]-MaxHeapSize) { 

/* we are running too low in store: 

T reload ourselves higher 
■/ 

_kernel_oafiie_bXock osf t 

/* reload so that the end of the word allocated 
for heapptr will be MaxHeapSize below the top 
F of allowed memory 

*/ 

int mybase = Qjt 8000 ; 

int newbase = regs.r[1]-MaaHeapsize- 

((int! heapptr - rciybase); 

char s[256]j 

char *irgs = ichar *} regs*r[Q]: 
while t'args! ’ * \ 5rgs++; 

/ w skip over the application name in 
F our argument string 

*/' 

osfnload = nirwbase; 

□5f.exec = Of f* load at our provided address * 
os f. st art - ( ir.t) H run Spat :: w ; 

CheckError ( 

keme 1 _osf ile (LoadFi 1 eUs i ngFat nVariat i e t rsajae, b osf) 

) ; 

spr int i is, M 3HAlN e go ■ x; 53 11 , newbase, args) ; 
system{s); 
f 

tree{heapptr ); 


static int cl j lVoid) 

l 


char b[256]j 
int ch* i; 

kerneloserror *§rr; 
err » NULL; 

/* prompt for input.,* */ 
printf f”cli> 11 1 ; 

/* skip leading spaces */ 
while ({eh = getcotainn = • 1 
± - 0; 

while fell 1 = ’\nM { 

/* EOF means kill cli() */ 

if (eh « EOF) [print f ( M \n n ) ; return(Q);f 

b[i+-i-l » dh; 

ch - getc[stdin)? 

1 

bti] = 0; 
if u ?“ 0) i 
char cE25£Jjr 
int res; 

strdpy(c P "CALL;"}; 
streat(c, b); 
res = system(cj; 

if (res — 0) err = _kernel_last__ terror U ; 

» 

if (err ! =NULL) printf < "error ■ i : is\n", 

err->errnum, 
i(err->ertmess)S r 

} 

return (Q); 

} 

int main (in* arge, char *argvl)) 

{ 

selfReloadtargv101); 
return cli() ; 

\ 
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SING THE LINKER 


The Linker is an essential program for anyont developing programs in a 
high-level compiled Language on the Archimedes personal work&tarion- Its 
purpose is to combine the contents of one or more object files (the output of 
.1 compiler or At&emfcltr) wirh one or more library files, producing a final 
executable program. 

SYNTAX 


The format ol the Link command is: 

Link -output fik I options } files 

The files arGumeni is a list of input ttEc^ this is described below, 
-output is the only compulsory keyword. 

Below is h list of the command tine options chat the Linker can rake. Most 
of these will only be used* occasionally. In the descriptions below, the 
important, frequently-used options arc given first, followed by the less 
common ones. Capital* are used to denote rhe alternative shortened form 
of the keyword, 

-Output 
-VIA 
-Case 
-Base 
-Verbose 
-Relocatable 
-Dbag 


Name of the linked output file 
Use a file to obtain (further) input file names 
Make matching of symbols case insensitive 
Set base address for output file 

Print messages indicating progress of the link operation 
Generate relocatable output file 

Generate an AOF image for use with the Dbug program 


Note* 

* The keyword -i cis - is followed by a numeric argument- You can use 
the prefix b to specify hexadecimal, and the suffixes k for 2^ and m 
for 

* The default base .iddress for rhe output file i% St8000 (J2K). If -dbutj 
i s -pecified, the default bn re address is Sc 50000 lie 32GK). 



* The item fik$ above is a list i-*r one or more iik names. icfrarated by 
{.puces. This pan of rhy cnrum^nd must he given Each of rhe I lies in 
the list miin he in Acorn Object Format {compiled tiles) or Acorn 
Library Format (libraries). They may contain reference*, to external 
objects {procedures rind variables) which the Linker will actempt i* ! 
resolve by matching them igaimt definitions found in other files 

* You can use wildcards in the filename list, Names using wildcards 
will be expanded into rhu list of files matching [he specificatum. For 
example, the name o.bas* might yield o.bastraln, o.basexpc, 

o . bas cmd- 

■* Usually, at least one library file will be specified m the list- A 
library is just a collect ion of \OF files stored in a single Acorn 
Library Format file- You can cull the procedures in the library for one 
language from programs written in another; as long as both languages 
conform ro the ARM Procedure Calling Standard and both run-time 
libraries use the common run-time kernel- For example, an assembler 
program COtdd uk; the C print f function, m long as the C nuviime 
system had been initialised, through the common run-time kernel 

* Libraries differ from object files in the « r ay the Sinker uSH them. 
Object files' symbols ate scanned only once when the linker arwmprs 
to resolve external reference*. Libraries are scanned as many times as 
necessary. If a required symbol is found in one of the libraries' 
component files, the whole component is incorp thTcJ into the output 
file. 

Two common errors given during a link are caused by unresolved and 
mu triple reterences. In rhe first case, a symbol has been referenced 
from a file (whose name is given in the emu), hut there is no 
corresponding definition for the symbol. This h usually caused by ihe 
omission of a required object or library file from the list, or rhe mis¬ 
spelling of a symbol in the original source program. 






Using the linker 

* The second error is caused by a clash of names. For example, a 
procedure might have hern defined with the name as a library 
procedure, or as a procedure in another object file, 

* The -outpur keyword is obligatory. It is followed by the nam e of the 
file to which the final linked program should ho written. If you jlm 
want to use I-ink to J-iuLk object tiles for unrest lived references. you can 
ipeeify [he device null ; as. rhe output tiler the final object code will 
be discarded. The output is usually in Arthur Image Format, which can 
be executed directly. An alternative format allow* low-level 
debugging with Dbug- 


Si triple examples 

Before we move on rt» describe the rest of the Link command's options, we 
give some examples us mg the syntax described so far 

Link: -OUTPUT test,«sieve aof.sisve, paslib 
Link -o %«inybasic aof.bas" lib. f 77 
Link -o noli: aof.coniF^ 


VIA KEYWORD 


Sometimes you may want to link a large number of input hies which would 
be tedious ro type on a command line, and whose names can'i conveniently 
he matched by a wildcard specification. To solve thi? problem, you can 
store a list ut input filenames in another tile and use the -via keyword ro 
use The Linker access ro them For example, suppose you created the file 
bar:-files wLth the contents: 

aof.main 
aof.expr 
aof.cmd 
aof. stnr.t 
aof.lex 
aof.filing 


aot + t;okens 


It you then ur>ed the command 

*link -o basic -via b&sf'iles lib 

then rhe hie? lifted in b,as files would be linked, together with the AOF 
file lib- 

CASE KEYWORD 

[f you specify - case in the command line, then the Linker will not treat the 
case of letters as significant tn identifiers- By default, the identifiers main 
and Main refer to different objects, as they art- r,pelr differetiT \y , However, 
with 

-case set, they are the same identifier. 

One reason for using this dag ii if you an: linking a C object file wirh one 
from a language such as ISO-Pascal or Fouran-77^ both of which are case 
iflitnsitLve. These languages plant symbols In object files in upper case, 
regardless of how they arc spelt in the source file, 

RASE KEYWORD 


By default, the base address of the output file ot the Linker is istyODO. This 
corresponds to the Start of .application workspace on the Archimedes 
computer, Alternatively, if the -dbug option is given, the base address is 
set to <So0OOD, This is $<> rhur rhe debugger program rebuff tan load at 
StSOOO as a normal application, and load the file to be debugged above 
itself, i There are other changes when ~dbua is given, as described below.) 

Using rhe - base keyword, you can set the base address of the output file 
to any desired value Fot example, you may want a program to have a high 
load address (as with the -ib'.'-j option set), bn still tie directly 
executable (which a dbug ide in AOF format isn'r), 
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The keyword is followed hy a number given rhe base address defined for 
the output filei eg -base tSOODD, -base 2 56k etc. When this is done, 
all relocatable objects in the input files arc relocated lining that base 
instead of the default. 

VERBOSE KEYWORD 

If you specify' boss on the command lme, the Linker goc* a KjK>n of 
ith progress. A message is printed as each file is opened and as each 
module is being relocated^ For example: 

link: opening p.basic 

link: opening o t baal 

link: opening o P bas2 

link: relocating module o.basl 

link: relocating module o.basZ 

link: relocating module ansilib (fpprintf] 

# + 4' 

RELOCATABLE KEYWORD 

Usually. when an image file is produced, it w r sll execute correctly only at 
the base address given (or the default). This is because the program wilt 
contain references to absolute addresses within itself- However, if you 
specify the -relocatable option, rhe final program will be relocatable, 

That is, tt can be loaded and executed at any address 

This tear a achieved bv adding a relocation table and a small program to 
perform the relocation to the image. The relocation table is a list of offsets 
from the sEart of the program to words which need relocating. These words 
are adjusted by the difference between the base address of the program 
and the address where ir was loaded. Once [he relocation h^s been 
performed, the program proper start* executing. 

Note char although this ibiliry can he used to make a program statically 
relocatable, if does not confirm nue position-independence on the program. 


That is, the program could not be moved in memory once it has carted and 
still he expected to work- 


PRl r G KEYWORD 


It a program is linked usi net rhe -Thug keyword, an executable image is 
not formed. Instead, an AOF file ls created which contains all of the 
symbols found tn the original source file*. The code segment of the file can 
he executed under the control of a Pbug program, and the content of ihc 
i: i>Ie and data segments may be ex a mined (and altered in the itase of the 
data segment). 

PREDEFINED LINKER SYMBOLS 

There are several symbols; which the Linkei knows about independently of 
any oi its input tiles- These start with ihe string Imaged$ and, along with 
all other external ruirri ccntasning S$. stt reserved by Ac.r.nm. 

The symbols are 


I rtiage S $ BO S 5 eas e 
Images5B055 Lima: 
I mags ? ? P.W ? ? Ba s e 
Images sp.vi-s $ I ir-1t: 


Address of rhe Starr of the read-only (code) ores 
Address of the hui j hevnnd rhe end ui code area 
Address < ■! the 4 tarc ot rhe read/write (data) area 
Address of the byte beyond the end of the data 
area 


Although it will often he rhe caw. Acorn do not guarantee that rhe end i>t 
the read-only area corresponds to the start "t the read/wnre area You 
should therefore not rely on this being mie 

The read-write (data* area may contain code as programs are sometimes 
Mrlf-mrsliksnc. Aim 1 1 irly- thr- read-only (code) ares may contain read-only 
data (eg siring lirerah in 1 doating-point constants; etc5 


These symbols can be imported as relocatable addresses by assembly 
language routines that miuht need them, 
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